Add API description for doxygen
authorJihun Ha <jihun.ha@samsung.com>
Mon, 25 Jul 2016 04:48:35 +0000 (13:48 +0900)
committerUze Choi <uzchoi@samsung.com>
Mon, 25 Jul 2016 08:45:05 +0000 (08:45 +0000)
For enrollee and mediator for c/c++, I add API description.

Change-Id: I571b4d83dfd046e5ed22a8cd250455b7e5feab38
Signed-off-by: Jihun Ha <jihun.ha@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/9673
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Hemant Mahsky <h.mahsky@samsung.com>
Reviewed-by: Uze Choi <uzchoi@samsung.com>
resource/docs/c-doc/Doxyfile
service/easy-setup/enrollee/inc/easysetup.h
service/easy-setup/inc/escommon.h
service/easy-setup/mediator/richsdk/inc/ESRichCommon.h

index 92144a37b2b1000cf52e32181d85d61c3bd19c14..dcd6bd73edf5cea23078409fe921ba0b839469bf 100644 (file)
@@ -681,8 +681,8 @@ INPUT                  = . \
                          ../../csdk/stack/include/internal/oicgroup.h \
                          ../../csdk/stack/include/internal/oickeepalive.h \
                          guides \
+                         ../../../service/easy-setup/inc \
                          ../../../service/easy-setup/enrollee/inc \
-                         ../../../service/easy-setup/enrollee/src/softap.h \
                          ../../../service/resource-directory/include \
 
 
index 6b65ca433999ee230e839e7b6ddefe7cfaf403c7..9b8cad2715e7e0474e30cc6da348282e80abd17f 100755 (executable)
@@ -70,6 +70,8 @@ ESResult ESInitEnrollee(bool isSecured, ESResourceMask resourceMask, ESProvision
  *
  * @param deviceProperty   Contains device information composed of WiFi Structure & DevConf Structure
  * @return ::ES_OK on success, some other value upon failure.
+ *
+ * @see ESDeviceProperty
  */
 ESResult ESSetDeviceProperty(ESDeviceProperty *deviceProperty);
 
@@ -79,6 +81,8 @@ ESResult ESSetDeviceProperty(ESDeviceProperty *deviceProperty);
  *
  * @param esState   Contains current enrollee's state.
  * @return ::ES_OK on success, some other value upon failure.
+ *
+ * @see ESEnrolleeState
  */
 ESResult ESSetState(ESEnrolleeState esState);
 
@@ -88,6 +92,8 @@ ESResult ESSetState(ESEnrolleeState esState);
  *
  * @param esErrCode   Contains enrollee's error code.
  * @return ::ES_OK on success, some other value upon failure.
+ *
+ * @see ESErrorCode
  */
 ESResult ESSetErrorCode(ESErrorCode esErrCode);
 
index e0577e78d81f781b4b641817256887c67daeb117..35ff2e8eea2e5e8b5b7e17fa1f98d7672a37fa52 100755 (executable)
@@ -78,39 +78,51 @@ extern "C"
 #define MAX_DEVICELEN   100
 #define MAX_WEBLINKLEN  100
 
+/**
+ * @brief  Supported WIFI mode like 802.11g and 802.11n
+ */
 typedef enum
 {
-    WiFi_11A = 0,
-    WiFi_11B,
-    WiFi_11G,
-    WiFi_11N,
-    WiFi_11AC,
-    WiFi_EOF = 999,
+    WiFi_11A = 0,       /**< 802.11a **/
+    WiFi_11B,           /**< 802.11b **/
+    WiFi_11G,           /**< 802.11g **/
+    WiFi_11N,           /**< 802.11n **/
+    WiFi_11AC,          /**< 802.11ac **/
+    WiFi_EOF = 999
 } WIFI_MODE;
 
+/**
+ * @brief  Supported WIFI frequency like 2.4G and 5G
+ */
 typedef enum
 {
-    WiFi_24G = 0,
-    WiFi_5G,
-    WiFi_BOTH
+    WiFi_24G = 0,       /**< 2.4G **/
+    WiFi_5G,            /**< 5G **/
+    WiFi_BOTH           /**< 2.4G and 5G **/
 } WIFI_FREQ;
 
+/**
+ * @brief  WIFI Authentication tlype of the Enroller
+ */
 typedef enum
 {
-    NONE_AUTH = 0,
-    WEP,
-    WPA_PSK,
-    WPA2_PSK
+    NONE_AUTH = 0,      /**< NO authentication **/
+    WEP,                /**< WEP **/
+    WPA_PSK,            /**< WPA-PSK **/
+    WPA2_PSK            /**< WPA2-PSK **/
 } WIFI_AUTHTYPE;
 
+/**
+ * @brief  WIFI encryption type of the Enroller
+ */
 typedef enum
 {
-    NONE_ENC = 0,
-    WEP_64,
-    WEP_128,
-    TKIP,
-    AES,
-    TKIP_AES
+    NONE_ENC = 0,       /**< NO encryption **/
+    WEP_64,             /**< WEP-64 **/
+    WEP_128,            /**< WEP-128**/
+    TKIP,               /**< TKIP **/
+    AES,                /**< AES **/
+    TKIP_AES            /**< TKIP-AES **/
 } WIFI_ENCTYPE;
 
 typedef enum
@@ -128,6 +140,9 @@ typedef enum
     ES_UNAUTHORIZED = 31
 } ESResult;
 
+/**
+ * @brief Indicate which resource is created in Enrollee
+ */
 typedef enum
 {
     ES_WIFI_RESOURCE = 0x01,
@@ -135,41 +150,64 @@ typedef enum
     ES_DEVCONF_RESOURCE = 0x04
 } ESResourceMask;
 
+/**
+ * @brief Data structure delivered from mediator, which provides WiFi information
+ */
 typedef struct
 {
-    char ssid[MAX_SSIDLEN]; /**< ssid of the Enroller**/
-    char pwd[MAX_CREDLEN]; /**< pwd of the Enroller**/
-    WIFI_AUTHTYPE authtype; /**< auth type of the Enroller**/
-    WIFI_ENCTYPE enctype; /**< encryption type of the Enroller**/
+    char ssid[MAX_SSIDLEN];         /**< Ssid of the Enroller**/
+    char pwd[MAX_CREDLEN];          /**< Pwd of the Enroller**/
+    WIFI_AUTHTYPE authtype;         /**< Auth type of the Enroller**/
+    WIFI_ENCTYPE enctype;           /**< Encryption type of the Enroller**/
 } ESWiFiProvData;
 
+/**
+ * @brief Data structure delivered from mediator, which provides device configuration information
+ */
 typedef struct
 {
-    char language[OIC_STRING_MAX_VALUE];
-    char country[OIC_STRING_MAX_VALUE];
+    char language[OIC_STRING_MAX_VALUE];    /**< IETF language tag using ISO 639X **/
+    char country[OIC_STRING_MAX_VALUE];     /**< ISO Country Code (ISO 3166-1 Alpha-2) **/
 } ESDevConfProvData;
 
+/**
+ * @brief Data structure delivered from mediator, which provides Cloud server information
+ */
 typedef struct
 {
-    char authCode[OIC_STRING_MAX_VALUE];
-    char authProvider[OIC_STRING_MAX_VALUE];
-    char ciServer[OIC_STRING_MAX_VALUE];
-    char serverID[OIC_STRING_MAX_VALUE];
+    char authCode[OIC_STRING_MAX_VALUE];        /**< Auth code issued by OAuth2.0-compatible account server **/
+    char authProvider[OIC_STRING_MAX_VALUE];    /**< Auth provider ID **/
+    char ciServer[OIC_STRING_MAX_VALUE];        /**< Cloud interface server URL which an Enrollee is going to registered **/
+    char serverID[OIC_STRING_MAX_VALUE];        /**< Cloud interface server UUID **/
 } ESCloudProvData;
 
+/**
+ * @brief Data structure stored for Device property which includes a WiFi and device configuration.
+ */
 typedef struct
 {
+    /**
+     * @brief Data structure indicating WiFi configuration of Enrollee
+     */
     struct
     {
         WIFI_MODE mode[NUM_WIFIMODE];
         WIFI_FREQ freq;
     } WiFi;
+
+    /**
+     * @brief Data structure indicating device configuration of Enrollee
+     */
     struct
     {
         char deviceName[MAX_DEVICELEN];
     } DevConf;
 } ESDeviceProperty;
 
+/**
+ * @brief Indicate enrollee and provisioning status. Provisioning status is shown in "provisioning
+ *        status" property in provisioning resource.
+ */
 typedef enum
 {
     /**
@@ -203,6 +241,9 @@ typedef enum
     ES_STATE_REGISTRRED_FAIL_TO_CLOUD
 } ESEnrolleeState, ProvStatus;
 
+/**
+ * @brief Indicate last error code to describe a reason of error during easy setup.
+ */
 typedef enum
 {
     /**
index 025c901ac22429d17a35fbcc7fe2d83f316a73f7..8fabe501671474b721722da19653207ae38fb6ed 100755 (executable)
@@ -93,10 +93,10 @@ namespace OIC
          */
         typedef enum
         {
-            NONE_AUTH = 0,
-            WEP,
-            WPA_PSK,
-            WPA2_PSK
+            NONE_AUTH = 0,      /**< NO authentication **/
+            WEP,                /**< WEP **/
+            WPA_PSK,            /**< WPA-PSK **/
+            WPA2_PSK            /**< WPA2-PSK **/
         } WIFI_AUTHTYPE;
 
         /**
@@ -104,67 +104,95 @@ namespace OIC
          */
         typedef enum
         {
-            NONE_ENC = 0,
-            WEP_64,
-            WEP_128,
-            TKIP,
-            AES,
-            TKIP_AES
+            NONE_ENC = 0,       /**< NO encryption **/
+            WEP_64,             /**< WEP-64 **/
+            WEP_128,            /**< WEP-128**/
+            TKIP,               /**< TKIP **/
+            AES,                /**< AES **/
+            TKIP_AES            /**< TKIP-AES **/
         } WIFI_ENCTYPE;
 
+        /**
+         * @brief  Supported WIFI frequency like 2.4G and 5G
+         */
         typedef enum
         {
-            WIFI_24G = 0,
-            WIFI_5G,
-            WIFI_BOTH
+            WIFI_24G = 0,       /**< 2.4G **/
+            WIFI_5G,            /**< 5G **/
+            WIFI_BOTH           /**< 2.4G and 5G **/
         } WIFI_FREQ;
 
+        /**
+         * @brief  Supported WIFI mode like 802.11g and 802.11n
+         */
         typedef enum
         {
-            WIFI_11A = 0,
-            WIFI_11B,
-            WIFI_11G,
-            WIFI_11N,
-            WIFI_11AC
+            WIFI_11A = 0,       /**< 802.11a **/
+            WIFI_11B,           /**< 802.11b **/
+            WIFI_11G,           /**< 802.11g **/
+            WIFI_11N,           /**< 802.11n **/
+            WIFI_11AC           /**< 802.11ac **/
         } WIFI_MODE;
 
+        /**
+         * @brief Data structure stored for Cloud server property provisioning
+         */
         typedef struct
         {
-            string authCode;
-            string authProvider;
-            string ciServer;
+            string authCode;        /**< Auth code issued by OAuth2.0-compatible account server **/
+            string authProvider;    /**< Auth provider ID **/
+            string ciServer;        /**< Cloud interface server URL which an Enrollee is going to registered **/
         } CloudProp;
 
+        /**
+         * @brief Data structure stored for Device property provisioning which includes a WiFi
+         *        and device configuration provisioning
+         */
         typedef struct
         {
+            /**
+             * @brief Data structure stored for WiFi property provisioning
+             */
             struct
             {
-                string ssid; /**< ssid of the Enroller**/
-                string pwd; /**< pwd of the Enroller**/
-                WIFI_AUTHTYPE authtype; /**< auth type of the Enroller**/
-                WIFI_ENCTYPE enctype; /**< encryption type of the Enroller**/
+                string ssid;            /**< Ssid of the Enroller **/
+                string pwd;             /**< Pwd of the Enroller **/
+                WIFI_AUTHTYPE authtype; /**< Auth type of the Enroller **/
+                WIFI_ENCTYPE enctype;   /**< Encryption type of the Enroller **/
             } WIFI;
 
+            /**
+             * @brief Data structure stored for device configuration property provisioning
+             */
             struct
             {
-                string language;
-                string country;
+                string language;        /**< IETF language tag using ISO 639X **/
+                string country;         /**< ISO Country Code (ISO 3166-1 Alpha-2) **/
             } Device;
         } DeviceProp;
 
+        /**
+         * @brief Data structure for received properties of device configuration resource
+         */
         typedef struct
         {
-            string name;
-            string language;
-            string country;
+            string name;        /**< Device's human-friendly name like device model name **/
+            string language;    /**< IETF language tag using ISO 639X **/
+            string country;     /**< ISO Country Code (ISO 3166-1 Alpha-2) **/
         } DeviceConfig;
 
+        /**
+         * @brief Data structure for received properties of WiFi resource
+         */
         typedef struct
         {
-            vector<WIFI_MODE> modes;
-            WIFI_FREQ freq;
+            vector<WIFI_MODE> modes;    /**< Supported WIFI mode like 802.11g and 802.11n **/
+            WIFI_FREQ freq;             /**< Supported WIFI frequency like 2.4G and 5G **/
         } WiFiConfig;
 
+        /**
+         * @brief Provisioning state in device property provisioning.
+         */
         typedef enum
         {
             ES_PROVISIONING_ERROR = -1,
@@ -173,15 +201,17 @@ namespace OIC
             ES_PROVISIONING_SUCCESS
         } ESDeviceProvState;
 
+        /**
+         * @brief Provisioning state in cloud server property provisioning.
+         */
         typedef enum
         {
-            ES_CLOUD_PROVISIONING_ERROR = -1,
-            ES_CLOUD_PROVISIONING_SUCCESS,
-            ES_CLOUD_ENROLLEE_FOUND,
-            ES_CLOUD_ENROLLEE_NOT_FOUND
+            ES_CLOUD_PROVISIONING_ERROR = -1,   /**< An error in cloud provisioning happens **/
+            ES_CLOUD_PROVISIONING_SUCCESS,      /**< Cloud provisioning is successfully done **/
+            ES_CLOUD_ENROLLEE_FOUND,            /**< An enrollee is found in a given network **/
+            ES_CLOUD_ENROLLEE_NOT_FOUND         /**< NO enrollee is found in a given network **/
         }ESCloudProvState;
 
-
         /**
          * Security Provisioning Status
          */
@@ -207,6 +237,11 @@ namespace OIC
             ESResult m_result;
         };
 
+        /**
+         * It comprises sets of WiFi and device configuration properties.
+         * Additionally, it provides a variable, m_cloudable, to make app know if
+         * the enrollee has a preference to register IoTivity cloud server.
+         */
         class EnrolleeConf
         {
         public:
@@ -240,6 +275,13 @@ namespace OIC
             bool m_cloudable;
         };
 
+        /**
+         * Status object for getConfiguration API. This object is given to application
+         * when a response for GET request to provisioning resource at Enrollee is arrived.
+         * It returns a result of the API and requested data delivered in the response
+         *
+         * @see EnrolleeConf
+         */
         class GetConfigurationStatus
         {
         public:
@@ -263,6 +305,11 @@ namespace OIC
             EnrolleeConf m_enrolleeConf;
         };
 
+        /**
+         * Status object for provisionDeviceProperties API. This object is given to application
+         * when a response for GET request to provisioning resource at Enrollee is arrived.
+         * It returns a result of the request.
+         */
         class DevicePropProvisioningStatus
         {
         public:
@@ -281,6 +328,13 @@ namespace OIC
             ESResult m_result;
         };
 
+        /**
+         * Status object for provisionCloudProperties API. This object is given to application
+         * when a response for GET request to provisioning resource at Enrollee is arrived.
+         * It returns a result of the request and status of this provisioning. The status provides
+         * an information if the enrollee is found in a given network and the provisioning is
+         * successfully done.
+         */
         class CloudPropProvisioningStatus
         {
         public: