service/easy-setup/enrollee/inc/easysetup.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Samsung Electronics 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 #ifndef EASYSETUP_ENROLLEE_H__
  23 #define EASYSETUP_ENROLLEE_H__
  24
  25 #include "escommon.h"
  26 #include "ESEnrolleeCommon.h"
  27
  28 /**
  29  * @file
  30  *
  31  * This file contains Enrollee APIs
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif // __cplusplus
  37
  38 /**
  39  * A function pointer for registering a user-defined function to set user-specific properties to a
  40  * response going back to a client.
  41  * @param payload Represents a response. You can set a specific value with specific property key
  42  * to the payload. If a client receives the response and know the property key, then it can
  43  * extract the value.
  44  * @param resourceType Used to distinguish which resource the received property belongs to.
  45  */
  46 typedef void (*ESWriteUserdataCb)(OCRepPayload* payload, char* resourceType);
  47
  48 /**
  49  * A function pointer for registering a user-defined function to parse user-specific properties from
  50  * received POST request.
  51  * @param payload Represents a received POST request. If you know user-specific property key,
  52  * then you can extract a corresponding value if it exists.
  53  * @param resourceType Used to distinguish which resource the received property belongs to
  54  * @param userdata User-specific data you want to deliver to desired users, i.e. application.
  55  * The user should know a data structure of passed userdata.
  56  */
  57 typedef void (*ESReadUserdataCb)(OCRepPayload* payload, char* resourceType, void** userdata);
  58
  59 /**
  60  * This function Initializes the EasySetup. This API must be called prior to invoking any other API
  61  *
  62  * @param isSecured         True if the Enrollee is operating in secured mode.
  63  * @param resourceMask      Provisining Resource Type which application wants to make.
  64  *                          ES_WIFI_RESOURCE = 0x01,
  65  *                          ES_CLOUD_RESOURCE = 0x02,
  66  *                          ES_DEVCONF_RESOURCE = 0x04
  67  * @param callbacks         ESProvisioningCallbacks for updating Provisioning Resources' data to the application
  68  * @return ::ES_OK on success, some other value upon failure.
  69  */
  70 ESResult ESInitEnrollee(bool isSecured, ESResourceMask resourceMask, ESProvisioningCallbacks callbacks);
  71
  72
  73 /**
  74  * This function Sets Device Information.
  75  *
  76  * @param deviceProperty   Contains device information composed of WiFi Structure & DevConf Structure
  77  * @return ::ES_OK on success, some other value upon failure.
  78  *
  79  * @see ESDeviceProperty
  80  */
  81 ESResult ESSetDeviceProperty(ESDeviceProperty *deviceProperty);
  82
  83
  84 /**
  85  * This function Sets Enrollee's State.
  86  *
  87  * @param esState   Contains current enrollee's state.
  88  * @return ::ES_OK on success, some other value upon failure.
  89  *
  90  * @see ESEnrolleeState
  91  */
  92 ESResult ESSetState(ESEnrolleeState esState);
  93
  94
  95 /**
  96  * This function Sets Enrollee's Error Code.
  97  *
  98  * @param esErrCode   Contains enrollee's error code.
  99  * @return ::ES_OK on success, some other value upon failure.
 100  *
 101  * @see ESErrorCode
 102  */
 103 ESResult ESSetErrorCode(ESErrorCode esErrCode);
 104
 105 /**
 106  * This function performs termination of Provisioning and Network resources.
 107  * Also terminates the IoTivity core stack.
 108  *
 109  * @return ::ES_OK on success, some other value upon failure.
 110  */
 111 ESResult ESTerminateEnrollee();
 112
 113 /**
 114  * This function is to set two function pointer to handle user-specific properties in in-comming
 115  * POST request and to out-going response for GET or POST request.
 116  * If you register certain functions with this API, you have to handle OCRepPayload structure to
 117  * set and get properties you want.
 118  *
 119  * @param readCb a callback for parsing properties from POST request
 120  * @param writeCb a callback for putting properties to a response to be sent
 121  *
 122  * @return ::ES_OK on success, some other value upon failure.
 123  *
 124  * @see ESReadUserdataCb
 125  * @see ESWriteUserdataCb
 126  */
 127 ESResult ESSetCallbackForUserdata(ESReadUserdataCb readCb, ESWriteUserdataCb writeCb);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif // __cplusplus
 132
 133
 134 #endif /* EASYSETUP_ENROLLEE_H__ */
 135