From bb300334afa2025eed5aa92d2eeb549bad3917b0 Mon Sep 17 00:00:00 2001 From: "saurabh.s9" Date: Fri, 19 Feb 2016 11:42:55 +0530 Subject: [PATCH] Resolved function description gaps. For C++ layer (Provisioning manager) Change-Id: I5b6d5e040bfc06e7b6d289b8cbc999245afa1249 Signed-off-by: saurabh.s9 Reviewed-on: https://gerrit.iotivity.org/gerrit/5065 Tested-by: jenkins-iotivity Reviewed-by: Habib Virji --- resource/include/OCProvisioningManager.h | 181 ++++++++++++++++++------------- 1 file changed, 106 insertions(+), 75 deletions(-) mode change 100644 => 100755 resource/include/OCProvisioningManager.h diff --git a/resource/include/OCProvisioningManager.h b/resource/include/OCProvisioningManager.h old mode 100644 new mode 100755 index 8c3553c..aecee19 --- a/resource/include/OCProvisioningManager.h +++ b/resource/include/OCProvisioningManager.h @@ -1,22 +1,22 @@ -/* ***************************************************************** - * - * Copyright 2015 Samsung Electronics All Rights Reserved. - * - * - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * *****************************************************************/ +//**************************************************************** +// +// Copyright 2015 Samsung Electronics All Rights Reserved. +// +//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= #ifndef OC_PROVISIONINGMANAGER_CXX_H_ #define OC_PROVISIONINGMANAGER_CXX_H_ @@ -44,7 +44,7 @@ namespace OC }; /** - * @brief: This class is for credential's to be set to devices. + * This class is for credential's to be set to devices. * The types supported are * 0: no security mode * 1: symmetric pair-wise key @@ -62,21 +62,44 @@ namespace OC Credential(OicSecCredType_t type, size_t size) : type(type), keySize(size) {} + /** + * API to get credential type of device. + * @return credential type of device. + */ OicSecCredType_t getCredentialType() const { return type; } + /** + * API to get size of credential key type. + * @return size of credential key type. + */ size_t getCredentialKeySize() const { return keySize; } + /** + * API to set credential type of device. + * Device can have following credential types + * - symmetric pair-wise key + * - symmetric group key + * - asymmetric key + * - signed asymmetric key (aka certificate) + * - PIN /password + * @param type credential type. + */ void setCredentialType(OicSecCredType_t type) { this->type = type; } + /** + * API to set size of credential key type. + * @param keySize credential key size. + * @note can be either 128 or 256 for symmetric pair-wise key + */ void setCredentialKeySize(size_t keySize) { this->keySize = keySize; @@ -87,12 +110,12 @@ namespace OC { public: /** - * The API is responsible for initializaton of the provisioning manager. It will load + * The API is responsible for initialization of the provisioning manager. It will load * provisioning database which have owned device's list and their linked status. * - * @param[in] dbPath file path of the sqlite3 db + * @param dbPath file path of the sqlite3 database. * - * @return OC_STACK_OK in case of success and other value otherwise. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult provisionInit(const std::string& dbPath); @@ -100,49 +123,49 @@ namespace OC * API is responsible for discovery of devices in it's subnet. It will list * all the device in subnet which are not yet owned. * - * @param[in] timeout Timeout in seconds, time util which function will listen to + * @param timeout Timeout in seconds, time until which function will listen to * responses from client before returning the list of devices. - * @param[out] list List of candidate devices to be provisioned - * @return OC_STACK_OK in case of success and other value otherwise. + * @param list List of candidate devices to be provisioned. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult discoverUnownedDevices(unsigned short timeout, DeviceList_t &list); /** * API is responsible for discovery of devices in it's subnet. It will list - * all the device in subnet which are already owned by calling provioning client + * all the device in subnet which are already owned by calling provisioning client. * - * @param[in] timeout Timeout in seconds, time util which function will listen to + * @param timeout Timeout in seconds, time until which function will listen to * responses from client before returning the list of devices. - * @param[out] list List of owned devices - * @return OC_STACK_OK in case of success and other value otherwise. + * @param list List of owned devices. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult discoverOwnedDevices(unsigned short timeout, DeviceList_t &list); /** - * API for registering Ownershipt transfer methods for a particular transfer Type + * API for registering Ownership transfer methods for a particular transfer Type. * - * @param[in] oxm Ownership transfer method - * @param[in] callbackData Methods for ownership transfer - * @param[in] inputPin callback method to input pin for verification - * @return OC_STACK_OK in case of success and other value otherwise. + * @param oxm Ownership transfer method. + * @param callbackData CallbackData Methods for ownership transfer. + * @param inputPin Callback method to input pin for verification. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult setOwnerTransferCallbackData(OicSecOxm_t oxm, OTMCallbackData_t* callbackData, InputPinCallback inputPin); /** * API to get status of all the devices in current subnet. The status include endpoint - * information and doxm information which can be extracted duing owned and unowned + * information and doxm information which can be extracted during owned and unowned * discovery. Along with this information, API will provide information about * devices' status. * Device can have following states * - ON/OFF: Device is switched on or off. * - * @param[in] timeout waitime for the API. - * @param[out] ownedDevList list of owned devices. - * @param[out] unownedDevList list of unowned devices. - * @return OC_STACK_OK in case of success and other value otherwise. + * @param timeout Wait time for the API. + * @param ownedDevList List of owned devices. + * @param unownedDevList List of unowned devices. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult getDevInfoFromNetwork(unsigned short timeout, DeviceList_t &ownedDevList, @@ -150,14 +173,14 @@ namespace OC /** * Server API to register callback to display stack generated PIN. * - * @param[in] displayPin GeneratePinCallback Method to display generated PIN. - * @return OC_STACK_OK in case of success and other value otherwise. + * @param displayPin Callback Method to Display generated PIN. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin); }; /** - * This class represents a Secure virtual Device, which can be provisioned by the + * This class represents a secure virtual device, which can be provisioned by the * provisioning client. */ class OCSecureResource @@ -176,13 +199,13 @@ namespace OC * API to provision credentials between two devices and ACLs for the devices who * act as a server. * - * @param[in] cred Type of credentials & key size to be provisioned to the device. - * @param[in] acl1 ACL for device 1. If this is not required set NULL. - * @param[in] device2 Second device to be provsioned. - * @param[in] acl2 ACL for device 2. If this is not required set NULL. - * @param[in] resultCallback Callback will be called when provisioning request recieves + * @param cred Type of credentials & key size to be provisioned to the device. + * @param acl1 ACL for device 1. If this is not required set NULL. + * @param device2 Second device to be provisioned. + * @param acl2 ACL for device 2. If this is not required set NULL. + * @param resultCallback Callback will be called when provisioning request receives * a response from first resource server. - * @return OC_STACK_OK in case of success and other value otherwise. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1, const OCSecureResource &device2, const OicSecAcl_t* acl2, @@ -191,19 +214,19 @@ namespace OC /** * API to do ownership transfer for un-owned device. * - * @param[in] resultCallback Result callback function to be invoked when + * @param resultCallback Result callback function to be invoked when * ownership transfer finished. - * @return OC_STACK_OK in case of success and other value otherwise. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult doOwnershipTransfer(ResultCallBack resultCallback); /** * API to send ACL information to resource. * - * @param[in] acl ACL to provision. - * @param[in] resultCallback callback will be called when provisioning request - * recieves a response from resource server. - * @return OC_STACK_OK in case of success and other value otherwise. + * @param acl ACL to provision. + * @param resultCallback Callback will be called when provisioning request + * receives a response from resource server. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult provisionACL(const OicSecAcl_t* acl, ResultCallBack resultCallback); @@ -211,35 +234,35 @@ namespace OC /** * API to provision credential to devices. * - * @param[in] cred Type of credentials to be provisioned to the device. - * @param[in] device2 Second device' instance,respresenting resourceto be provsioned. - * @param[in] resultCallback callback will be called when provisioning request recieves + * @param cred Type of credentials to be provisioned to the device. + * @param device2 Second device' instance, representing resource to be provisioned. + * @param resultCallback Callback will be called when provisioning request receives * a response from first resource server. - * @return OC_STACK_OK in case of success and other value otherwise. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult provisionCredentials(const Credential &cred, const OCSecureResource &device2, ResultCallBack resultCallback); - /* - * API to remove the credential & relasionship between the two devices. + /** + * API to remove the credential & relationship between the two devices. * - * @param[in] pTargetDev2 second device information to be unlinked. - * @param[in] resultCallback callback provided by API user, callback will be called when + * @param device2 Second device information to be unlinked. + * @param resultCallback Callback provided by API user, callback will be called when * device unlink is finished. - * @return OC_STACK_OK in case of success and other value otherwise. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult unlinkDevices(const OCSecureResource &device2, ResultCallBack resultCallback); - /* + /** * API to remove device credential from all devices in subnet. * - * @param[in] resultCallback callback provided by API user, callback will be called when + * @param resultCallback Callback provided by API user, callback will be called when * credential revocation is finished. - * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device - * discovery.(seconds) - * @return OC_STACK_OK in case of success and other value otherwise. + * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device + * discovery in seconds. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery, ResultCallBack resultCallback); @@ -247,30 +270,38 @@ namespace OC /** * This method is used to get linked devices' IDs. * - * @param[out] uuidList information about the list of linked devices' uuids. - * @return OC_STACK_OK in case of success and other value otherwise. + * @param uuidList Information about the list of linked devices uuids. + * @return ::OC_STACK_OK in case of success and other value otherwise. */ OCStackResult getLinkedDevices(UuidList_t &uuidList); /** - * API to get the DeviceID of this resource + * API to get the device ID of this resource. + * @return device ID. */ std::string getDeviceID(); + /** + * API to get the information of device for provisioning. + * @return @ref OCProvisionDev_t Reference provides information of device for provisioning. + */ OCProvisionDev_t* getDevPtr()const; /** - * This function returns the Device's IP addr. + * This function returns the device's IP address. + * @return device address. */ std::string getDevAddr(); /** - * This function returns the Device's Status + * This function returns the device's Status. + * @return Device status (1 = ON and 2 = OFF). */ int getDeviceStatus(); /** - * This function provides the OWNED status of the device. + * This function provides the owned status of the device. + * @return Device owned status. */ bool getOwnedStatus(); -- 2.7.4