1 //******************************************************************
3 // Copyright 2015 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
24 * This API only works with:
30 #ifndef TELEGESISSOCKET_H_
31 #define TELEGESISSOCKET_H_
38 #include "plugininterface.h"
69 * Represents a single line within TWEntry struct.
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.
81 typedef struct TWEntry
83 /** A pointer to the list of lines */
85 /** Number of lines in this entry. */
87 /** The type of entry. This maps with the leading tag of any given AT response/prompt. */
89 /** First two characters are an AT Error Code,
90 while third character is NULL terminator so it can be printed */
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.
98 * Starts socket communication with the Telegesis Dongle at com location.
100 * @param plugin The plugin' scope which the socket ops will operate within.
102 * @param fileLoc The file descriptor location on the file system to start.
104 TWResultCode TWStartSock(PIPlugin * plugin, const char * fileLoc);
107 * Issues command to a specific Telegesis Dongle.
109 * @param plugin The plugin' scope which the command will be issued.
111 * @param command The command to be issued to the Telegesis Dongle.
113 TWResultCode TWIssueATCommand(PIPlugin * plugin, const char * command);
116 * Returns a response/prompt. If NULL, no response or prompts have been issued
117 * back by the Telegesis Dongle.
119 * @param plugin The plugin' scope which the socket is managed within.
121 * @param entry The line(s) which correspond to a single entry in the
122 * response/prompt queue. Returned by-reference.
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
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.
132 TWResultCode TWDequeueEntry(PIPlugin * plugin, TWEntry ** entry, TWEntryType type);
135 * Helper function to deallocate memory of a TWEntry.
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.
141 * @param plugin The plugin' scope which the socket is managed within.
143 * @param entry The entry that was dequeued by calling TWDequeueLine.
145 TWResultCode TWDeleteEntry(PIPlugin * plugin, TWEntry * entry);
148 * Helper function to retrieve the current radio's EUI.
150 * @param plugin The plugin' scope which the socket is managed within.
152 * @param eui The local radio's EUI.
154 TWResultCode TWGetEUI(PIPlugin * plugin, char ** eui);
157 * Stops socket communication with the Telegesis Dongle within scope of plugin.
159 * @param plugin The plugin' scope the socket ops cease to operate within.
161 TWResultCode TWStopSock(PIPlugin * plugin);
165 #endif // __cplusplus
167 #endif /* TELEGESISSOCKET_H_ */