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_NONE,
  63     TW_MAX_ENTRY
  64 } TWEntryType;
  65
  66 /**
  67  * Represents a single line within TWEntry struct.
  68  */
  69 typedef struct
  70 {
  71     const char * line;
  72     int length;
  73 } TWLine;
  74
  75 /**
  76  * Represents a queue item. This is structure built after incoming data from the
  77  * Telegesis adapter has put something in the buffer. A single TWEntry can contain 0+ TWLines.
  78  */
  79 typedef struct TWEntry
  80 {
  81     /** A pointer to the list of lines */
  82     TWLine * lines;
  83     /** Number of lines in this entry. */
  84     int count;
  85     /** The type of entry. This maps with the leading tag of any given AT response/prompt. */
  86     TWEntryType type;
  87     /** First two characters are an AT Error Code,
  88         while third character is NULL terminator so it can be printed */
  89     char atErrorCode[3];
  90     /** Any read, write, parsing, or system errors are captured in this generic resultCode. */
  91     TWResultCode resultCode;
  92     struct TWEntry * next; // Ignore; Used internally to manage the queue.
  93 } TWEntry;
  94
  95 /**
  96  * Starts socket communication with the Telegesis Dongle at com location.
  97  *
  98  * @param plugin The plugin' scope which the socket ops will operate within.
  99  *
 100  * @param fileLoc The file descriptor location on the file system to start.
 101  */
 102 TWResultCode TWStartSock(PIPlugin * plugin, const char * fileLoc);
 103
 104 /**
 105  * Issues command to a specific Telegesis Dongle.
 106  *
 107  * @param plugin The plugin' scope which the command will be issued.
 108  *
 109  * @param command The command to be issued to the Telegesis Dongle.
 110  */
 111 TWResultCode TWIssueATCommand(PIPlugin * plugin, const char * command);
 112
 113 /**
 114  * Returns a response/prompt. If NULL, no response or prompts have been issued
 115  * back by the Telegesis Dongle.
 116  *
 117  * @param plugin The plugin' scope which the socket is managed within.
 118  *
 119  * @param entry The line(s) which correspond to a single entry in the
 120  * response/prompt queue. Returned by-reference.
 121  *
 122  * @param type The type of entry this queue item is. If not specified as TW_NONE,
 123  * this API will block (for up to 5 Seconds) until an entry with the specified type
 124  * has been enqueued.
 125  *
 126  * @brief Its best to call this function in a loop. Break from loop when this
 127  * function returns NULL. Otherwise, handle the data in TWEntry. Release
 128  * memory allocated by this function by passing the entry into TWDeleteEntry.
 129  */
 130 TWResultCode TWDequeueEntry(PIPlugin * plugin, TWEntry ** entry, TWEntryType type);
 131
 132 /**
 133  * Helper function to deallocate memory of a TWEntry.
 134  *
 135  * Use this function when you are finished using the entry returned after
 136  * calling TWDequeueLine. This will ensure your utilization of this API does
 137  * not lead to memory leaks in your application.
 138  *
 139  * @param plugin The plugin' scope which the socket is managed within.
 140  *
 141  * @param entry The entry that was dequeued by calling TWDequeueLine.
 142  */
 143 TWResultCode TWDeleteEntry(PIPlugin * plugin, TWEntry * entry);
 144
 145 /**
 146  * Helper function to retrieve the current radio's EUI.
 147  *
 148  * @param plugin The plugin' scope which the socket is managed within.
 149  *
 150  * @param eui The local radio's EUI.
 151  */
 152 TWResultCode TWGetEUI(PIPlugin * plugin, char ** eui);
 153
 154 /**
 155  * Stops socket communication with the Telegesis Dongle within scope of plugin.
 156  *
 157  * @param plugin The plugin' scope the socket ops cease to operate within.
 158  */
 159 TWResultCode TWStopSock(PIPlugin * plugin);
 160
 161 #ifdef __cplusplus
 162 }
 163 #endif // __cplusplus
 164
 165 #endif /* TELEGESISSOCKET_H_ */