CayenneUtils.h

00001 /*
00002 The MIT License(MIT)
00003 
00004 Cayenne MQTT Client Library
00005 Copyright (c) 2016 myDevices
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
00008 documentation files(the "Software"), to deal in the Software without restriction, including without limitation
00009 the rights to use, copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the Software,
00010 and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
00011 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
00012 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
00013 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE AUTHORS OR
00014 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00015 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00016 
00017 */
00018 
00019 #ifndef _CAYENNEUTILS_h
00020 #define _CAYENNEUTILS_h
00021 
00022 #if defined(__cplusplus)
00023 extern "C" {
00024 #endif
00025 
00026 #if defined(WIN32_DLL) || defined(WIN64_DLL)
00027 #define DLLImport __declspec(dllimport)
00028 #define DLLExport __declspec(dllexport)
00029 #elif defined(LINUX_SO)
00030 #define DLLImport extern
00031 #define DLLExport  __attribute__ ((visibility ("default")))
00032 #else
00033 #define DLLImport
00034 #define DLLExport
00035 #endif
00036 
00037 #include <stdio.h>
00038 #include "CayenneDefines.h"
00039 
00040 enum CayenneReturnCode { CAYENNE_BUFFER_OVERFLOW = -2, CAYENNE_FAILURE = -1, CAYENNE_SUCCESS = 0 };
00041 
00042 /**
00043 * A unit/value pair used in Cayenne payloads.
00044 */
00045 typedef struct CayenneValuePair
00046 {
00047     const char* unit; /**< The data unit. */
00048     const char* value; /**< The data value. */
00049 } CayenneValuePair;
00050 
00051 /**
00052 * Build a specified topic string.
00053 * @param[out] topicName Returned topic string
00054 * @param[in] length CayenneTopic buffer length
00055 * @param[in] username Cayenne username
00056 * @param[in] clientID Cayennne client ID
00057 * @param[in] topic Cayenne topic
00058 * @param[in] channel The topic channel, use CAYENNE_NO_CHANNEL if none is required, CAYENNE_ALL_CHANNELS if a wildcard is required
00059 * @return CAYENNE_SUCCESS if topic string was created, error code otherwise
00060 */
00061 DLLExport int CayenneBuildTopic(char* topicName, size_t length, const char* username, const char* clientID, CayenneTopic topic, unsigned int channel);
00062 
00063 /**
00064 * Build a specified data payload.
00065 * @param[out] payload Returned payload
00066 * @param[in,out] length Payload buffer length
00067 * @param[in] type Optional type to use for type,unit=value payload, can be NULL
00068 * @param[in] values Unit/value array
00069 * @param[in] valueCount Number of values
00070 * @return CAYENNE_SUCCESS if topic string was created, error code otherwise
00071 */
00072 DLLExport int CayenneBuildDataPayload(char* payload, size_t* length, const char* type, const CayenneValuePair* values, size_t valueCount);
00073 
00074 /**
00075 * Build a specified response payload.
00076 * @param[out] payload Returned payload
00077 * @param[in,out] length Payload buffer length
00078 * @param[in] id ID of message the response is for
00079 * @param[in] error Optional error message, NULL for success
00080 * @return CAYENNE_SUCCESS if topic string was created, error code otherwise
00081 */
00082 DLLExport int CayenneBuildResponsePayload(char* payload, size_t* length, const char* id, const char* error);
00083 
00084 /**
00085 * Parse a topic string in place. This may modify the topic string.
00086 * @param[out] topic Returned Cayenne topic
00087 * @param[out] channel Returned channel, CAYENNE_NO_CHANNEL if there is none
00088 * @param[out] clientID Returned client ID
00089 * @param[in] username Cayenne username
00090 * @param[in] topicName Topic name string
00091 * @param[in] length Topic name string length
00092 * @return CAYENNE_SUCCESS if topic was parsed, error code otherwise
00093 */
00094 DLLExport int CayenneParseTopic(CayenneTopic* topic, unsigned int* channel, const char** clientID, const char* username, char* topicName, unsigned int length);
00095 
00096 /**
00097 * Parse a null terminated payload in place. This may modify the payload string. 
00098 * @param[out] values Returned payload data unit & value array
00099 * @param[in,out] valuesSize Size of values array, returns the count of values in the array
00100 * @param[out] type Returned type, NULL if there is none
00101 * @param[out] id Returned message id, empty string if there is none
00102 * @param[in] topic Cayenne topic
00103 * @param[in] payload Payload string, must be null terminated.
00104 * @return CAYENNE_SUCCESS if topic string was created, error code otherwise
00105 */
00106 DLLExport int CayenneParsePayload(CayenneValuePair* values, size_t* valuesSize, const char** type, const char** id, CayenneTopic topic, char* payload);
00107 
00108 #if defined(__cplusplus)
00109 }
00110 #endif
00111 
00112 #endif