plugins/zigbee_wrapper/telegesis_wrapper/include/telegesis_socket.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 /**
  22  * @file
  23  *
  24  * This API only works with:
  25  *      Telegesis ETRX357
  26  *      CICIE R310 B110615
  27  *
  28  */
  29
  30 #ifndef TELEGESISSOCKET_H_
  31 #define TELEGESISSOCKET_H_
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif // __cplusplus
  36
  37 #include "twtypes.h"
  38 #include "plugininterface.h"
  39
  40 typedef enum
  41 {
  42     TW_NETWORK_INFO = 0,
  43     TW_JPAN,
  44     TW_RFD,
  45     TW_FFD,
  46     TW_SED,
  47     TW_ZED,
  48     TW_MATCHDESC,
  49     TW_SIMPLEDESC,
  50     TW_INCLUSTER,
  51     TW_WRITEATTR,
  52     TW_RESPATTR,
  53     TW_TEMPERATURE,
  54     TW_DFTREP,
  55     TW_DRLOCRSP,
  56     TW_DRUNLOCKRSP,
  57     TW_ACK,
  58     TW_NACK,
  59     TW_SEQ,
  60     TW_ZENROLLREQ,
  61     TW_ENROLLED,
  62     TW_ZONESTATUS,
  63     TW_ADDRESS_RESPONSE,
  64     TW_NONE,
  65     TW_MAX_ENTRY
  66 } TWEntryType;
  67
  68 /**
  69  * Represents a single line within TWEntry struct.
  70  */
  71 typedef struct
  72 {
  73     const char * line;
  74     int length;
  75 } TWLine;
  76
  77 /**
  78  * Represents a queue item. This is structure built after incoming data from the
  79  * Telegesis adapter has put something in the buffer. A single TWEntry can contain 0+ TWLines.
  80  */
  81 typedef struct TWEntry
  82 {
  83     /** A pointer to the list of lines */
  84     TWLine * lines;
  85     /** Number of lines in this entry. */
  86     int count;
  87     /** The type of entry. This maps with the leading tag of any given AT response/prompt. */
  88     TWEntryType type;
  89     /** First two characters are an AT Error Code,
  90         while third character is NULL terminator so it can be printed */
  91     char atErrorCode[3];
  92     /** Any read, write, parsing, or system errors are captured in this generic resultCode. */
  93     TWResultCode resultCode;
  94     struct TWEntry * next; // Ignore; Used internally to manage the queue.
  95 } TWEntry;
  96
  97 /**
  98  * Starts socket communication with the Telegesis Dongle at com location.
  99  *
 100  * @param plugin The plugin' scope which the socket ops will operate within.
 101  *
 102  * @param fileLoc The file descriptor location on the file system to start.
 103  */
 104 TWResultCode TWStartSock(PIPlugin * plugin, const char * fileLoc);
 105
 106 /**
 107  * Issues command to a specific Telegesis Dongle.
 108  *
 109  * @param plugin The plugin' scope which the command will be issued.
 110  *
 111  * @param command The command to be issued to the Telegesis Dongle.
 112  */
 113 TWResultCode TWIssueATCommand(PIPlugin * plugin, const char * command);
 114
 115 /**
 116  * Returns a response/prompt. If NULL, no response or prompts have been issued
 117  * back by the Telegesis Dongle.
 118  *
 119  * @param plugin The plugin' scope which the socket is managed within.
 120  *
 121  * @param entry The line(s) which correspond to a single entry in the
 122  * response/prompt queue. Returned by-reference.
 123  *
 124  * @param type The type of entry this queue item is. If not specified as TW_NONE,
 125  * this API will block (for up to 5 Seconds) until an entry with the specified type
 126  * has been enqueued.
 127  *
 128  * @brief Its best to call this function in a loop. Break from loop when this
 129  * function returns NULL. Otherwise, handle the data in TWEntry. Release
 130  * memory allocated by this function by passing the entry into TWDeleteEntry.
 131  */
 132 TWResultCode TWDequeueEntry(PIPlugin * plugin, TWEntry ** entry, TWEntryType type);
 133
 134 /**
 135  * Helper function to deallocate memory of a TWEntry.
 136  *
 137  * Use this function when you are finished using the entry returned after
 138  * calling TWDequeueLine. This will ensure your utilization of this API does
 139  * not lead to memory leaks in your application.
 140  *
 141  * @param plugin The plugin' scope which the socket is managed within.
 142  *
 143  * @param entry The entry that was dequeued by calling TWDequeueLine.
 144  */
 145 TWResultCode TWDeleteEntry(PIPlugin * plugin, TWEntry * entry);
 146
 147 /**
 148  * Helper function to retrieve the current radio's EUI.
 149  *
 150  * @param plugin The plugin' scope which the socket is managed within.
 151  *
 152  * @param eui The local radio's EUI.
 153  */
 154 TWResultCode TWGetEUI(PIPlugin * plugin, char ** eui);
 155
 156 /**
 157  * Stops socket communication with the Telegesis Dongle within scope of plugin.
 158  *
 159  * @param plugin The plugin' scope the socket ops cease to operate within.
 160  */
 161 TWResultCode TWStopSock(PIPlugin * plugin);
 162
 163 #ifdef __cplusplus
 164 }
 165 #endif // __cplusplus
 166
 167 #endif /* TELEGESISSOCKET_H_ */