Diff: serializer.h

Revision:

2:d9c585174187

Parent:

0:1f9b2707ec7d

diff -r f20abf1e13e9 -r d9c585174187 serializer.h
--- a/serializer.h	Wed Sep 16 22:42:57 2015 -0700
+++ b/serializer.h	Tue Sep 22 20:36:53 2015 -0700
@@ -1,6 +1,40 @@
 // Copyright (c) Microsoft. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+/** @file   serializer.h
+*	@brief	The IoT Hub Serializer APIs allows developers to define models for
+*			their devices
+*
+*	@details	The IoT Hub Serializer APIs allows developers to quickly and easily define
+*				models for their devices directly as code, while supporting the required
+*				features for modeling devices (including multiple models and multiple
+*				devices within the same application). For example:
+*				
+*		<pre>
+*       BEGIN_NAMESPACE(Contoso);
+*       
+*           DECLARE_STRUCT(SystemProperties,
+*               ascii_char_ptr, DeviceID,
+*               _Bool, Enabled
+*           );
+*           
+*           DECLARE_MODEL(VendingMachine,
+*           
+*               WITH_DATA(int, SensorValue),
+*           
+*               WITH_DATA(ascii_char_ptr, ObjectName),
+*               WITH_DATA(ascii_char_ptr, ObjectType),
+*               WITH_DATA(ascii_char_ptr, Version),
+*               WITH_DATA(SystemProperties, SystemProperties),
+*               WITH_DATA(ascii_char_ptr_no_quotes, Commands),
+*           
+*               WITH_ACTION(SetItemPrice, ascii_char_ptr, itemId, ascii_char_ptr, price)
+*           );
+*       
+*       END_NAMESPACE(Contoso);
+*       </pre>
+*/
+
 #ifndef SERIALIZER_H
 #define SERIALIZER_H
 
@@ -46,13 +80,33 @@
 
 /* IOT Agent Macros */
 
+/**
+ * @def BEGIN_NAMESPACE(schemaNamespace)
+ * This macro marks the start of a section that declares IOT model
+ * elements (like complex types, etc.). Declarations are typically
+ * placed in header files, so that they can be shared between
+ * translation units.
+ */
 /* Codes_SRS_SERIALIZER_99_001:[For each completed schema declaration block, a unique storage container for schema metadata shall be available in the translation unit at runtime.] */
 #define BEGIN_NAMESPACE(schemaNamespace) \
     REFLECTED_END_OF_LIST
 
+/**
+* @def END_NAMESPACE(schemaNamespace)
+* This macro marks the end of a section that declares IOT model
+* elements.
+*/
 #define END_NAMESPACE(schemaNamespace) \
     REFLECTED_LIST_HEAD(schemaNamespace)
 
+/**
+* @def DECLARE_STRUCT(name, ...)
+* This macro allows the definition of a struct type that can then be used as
+* part of a model definition.
+* 
+* @param name                      Name of the struct
+* @param element1, element2...     Specifies a list of struct members
+*/
 /* Codes_SRS_SERIALIZER_99_080:[ The DECLARE_STRUCT declaration shall insert metadata describing a complex data type.] */
 #define DECLARE_STRUCT(name, ...) \
     /* Codes_SRS_SERIALIZER_99_096:[ DECLARE_STRUCT shall declare a matching C struct data type named name, which can be referenced from any code that can access the declaration.] */ \
@@ -89,6 +143,21 @@
         FOR_EACH_2_KEEP_1(UNBUILD_DESTINATION_FIELD, value, __VA_ARGS__); \
     }
 
+/**
+ * @def     DECLARE_MODEL(name, ...)
+ * This macro allows declaring a model that can be later used to instantiate
+ * a device.
+ * 		    
+ * @param   name                        Specifies the model name
+ * @param   element1, element2...       Specifies a model element which can be
+ * 		                                a property or an action.
+ * 		                                    - A property is described in a  
+ * 		                                      model by using the WITH_DATA
+ * 		                                    - An action is described in a  
+ * 		                                      model by using the ::WITH_ACTION
+ * 		                                      macro.
+ *
+ */
 /* WITH_DATA's name argument shall be one of the following data types: */
 /* Codes_SRS_SERIALIZER_99_133:[a model type introduced previously by DECLARE_MODEL] */
 #define DECLARE_MODEL(name, ...) \
@@ -97,11 +166,54 @@
     FOR_EACH_1_KEEP_1(CREATE_MODEL_ELEMENT, name, __VA_ARGS__) \
     TO_AGENT_DATA_TYPE(name, DROP_FIRST_COMMA_FROM_ARGS(EXPAND_MODEL_ARGS(__VA_ARGS__)))
 
+/**
+ * @def   WITH_DATA(type, name)
+ * The ::WITH_DATA macro allows declaring a model property in a model. A
+ * property can be published by using the ::SERIALIZE macro.
+ *
+ * @param   type    Specifies the property type. Can be any of the following
+ *                  types:
+ *                   - int
+ *                   - double
+ *                   - float
+ *                   - long
+ *                   - int8_t
+ *                   - uint8_t
+ *                   - int16_t
+ *                   - int32_t
+ *                   - int64_t
+ *                   - bool
+ *                   - ascii_char_ptr
+ *                   - EDM_DATE_TIME_OFFSET
+ *                   - EDM_GUID
+ *                   - EDM_BINARY
+ *                   - Any struct type previously introduced by another ::DECLARE_STRUCT.
+ *                  
+ * @param   name    Specifies the property name
+ */
 #define WITH_DATA(type, name) MODEL_PROPERTY(type, name)
 
+/**
+ * @def   WITH_ACTION(name, ...)
+ * The ::WITH_ACTION macro allows declaring a model action.
+ *
+ * @param   name                    Specifies the action name.
+ * @param   argXtype, argXName...   Defines the type and name for the X<sup>th</sup>
+ *                                  argument of the action. The type can be any of
+ *                                  the primitive types or a struct type.
+ */
 /*Codes_SRS_SERIALIZER_99_039:[WITH_ACTION shall declare an action of the current data provider called as the first macro parameter(name) and having the first parameter called parameter1Name of type parameter1Type, the second parameter named parameter2Name having the type parameter2Type and so on.]*/
 #define WITH_ACTION(name, ...)  MODEL_ACTION(name, __VA_ARGS__)
 
+/**
+ * @def   GET_MODEL_HANDLE(schemaNamespace, modelName)
+ * The ::GET_MODEL_HANDLE macro returns a model handle that can be used in
+ * subsequent operations like generating the CSDL schema for the model,
+ * uploading the schema, creating a device, etc.
+ * 
+ * @param   schemaNamespace The namespace to which the model belongs.
+ * @param   modelName       The name of the model.
+ */
 /* Codes_SRS_SERIALIZER_99_110:[ The GET_MODEL_HANDLE function macro shall first register the schema by calling CodeFirst_RegisterSchema, passing schemaNamespace and a pointer to the metadata generated in the schema declaration block.] */
 /* Codes_SRS_SERIALIZER_99_094:[ GET_MODEL_HANDLE shall then call Schema_GetModelByName, passing the schemaHandle obtained from CodeFirst_RegisterSchema and modelName arguments, to retrieve the SCHEMA_MODEL_TYPE_HANDLE corresponding to the modelName argument.] */
 /* Codes_SRS_SERIALIZER_99_112:[ GET_MODEL_HANDLE will return the handle for the named model.] */
@@ -127,11 +239,35 @@
 #define DESTROY_MODEL_INSTANCE(deviceData) \
     CodeFirst_DestroyDevice(deviceData)
 
+/**
+ * @def      SERIALIZE(destination, destinationSize,...)
+ * This macro produces JSON serialized representation of the properties.
+ * 
+ * @param   destination                  Pointer to an @c unsigned @c char* that
+ *                                       will receive the serialized data.
+ * @param   destinationSize              Pointer to a @c size_t that gets
+ *                                       written with the size in bytes of the
+ *                                       serialized data
+ * @param    property1, property2...     A list of property values to send. The
+ *                                       order in which the properties appear in
+ *                                       the list does not matter, all values
+ *                                       will be sent together.
+ *
+ */
 /*Codes_SRS_SERIALIZER_99_113:[ SERIALIZE shall call CodeFirst_SendAsync, passing a destination, destinationSize, the number of properties to publish, and pointers to the values for each property.] */
 /*Codes_SRS_SERIALIZER_99_117:[ If CodeFirst_SendAsync succeeds, SEND will return IOT_AGENT_OK.] */
 /*Codes_SRS_SERIALIZER_99_114:[ If CodeFirst_SendAsync fails, SEND shall return IOT_AGENT_SERIALIZE_FAILED.] */
 #define SERIALIZE(destination, destinationSize,...) ((CodeFirst_SendAsync(destination, destinationSize, COUNT_ARG(__VA_ARGS__) FOR_EACH_1(ADDRESS_MACRO, __VA_ARGS__)) == CODEFIRST_OK) ? IOT_AGENT_OK : IOT_AGENT_SERIALIZE_FAILED)
 
+/**
+ * @def   EXECUTE_COMMAND(device, command)
+ * Any action that is declared in a model must also have an implementation as
+ * a C function.
+ *
+ * @param   device      Pointer to device data.
+ * @param   command     Values that match the arguments declared in the model
+ *                      action.
+ */
 /*Codes_SRS_SERIALIZER_02_018: [EXECUTE_COMMAND macro shall call CodeFirst_ExecuteCommand passing device, commandBuffer and commandBufferSize.]*/
 #define EXECUTE_COMMAND(device, command) (CodeFirst_ExecuteCommand(device, command))