X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=resource%2Fcsdk%2Fstack%2Finclude%2Focstack.h;h=2a9f595464da0af7bef6e673439f4b88d4a552b3;hb=refs%2Ftags%2Faccepted%2Ftizen%2Funified%2F20171010.063815;hp=9eeae7ec505c885de71ebd6a8e7275d4ee0be9ac;hpb=d2f4378179667e7b55b38af7af11e639bea10885;p=platform%2Fupstream%2Fiotivity.git diff --git a/resource/csdk/stack/include/ocstack.h b/resource/csdk/stack/include/ocstack.h index 9eeae7e..2a9f595 100644 --- a/resource/csdk/stack/include/ocstack.h +++ b/resource/csdk/stack/include/ocstack.h @@ -57,6 +57,19 @@ OCStackResult OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlag /** * This function Initializes the OC Stack. Must be called prior to starting the stack. * + * @param mode OCMode Host device is client, server, or client-server. + * @param serverFlags OCTransportFlags Default server transport flags. + * @param clientFlags OCTransportFlags Default client transport flags. + * @param transportType OCTransportAdapter value to initialize. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult OCInit2(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags, + OCTransportAdapter transportType); + +/** + * This function Initializes the OC Stack. Must be called prior to starting the stack. + * * @param ipAddr IP Address of host device. Deprecated parameter. * @param port Port of host device. Deprecated parameter. * @param mode OCMode Host device is client, server, or client-server. @@ -118,6 +131,8 @@ OCStackResult OCProcess(); * This function discovers or Perform requests on a specified resource * (specified by that Resource's respective URI). * + * @deprecated: Use OCDoRequest instead which does not free given payload. + * * @param handle To refer to the request sent out on behalf of * calling this API. This handle can be used to cancel this operation * via the OCCancel API. @@ -125,10 +140,11 @@ OCStackResult OCProcess(); * the consumer. A NULL handle is permitted in the event where the caller * has no use for the return value. * @param method To perform on the resource. - * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in + * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in * favor of destination.) * @param destination Complete description of destination. - * @param payload Encoded request payload. + * @param payload Encoded request payload, + OCDoResource will free given payload when return OC_STATUS_OK. * @param connectivityType Modifier flags when destination is not given. * @param qos Quality of service. Note that if this API is called on a uri with the * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS @@ -148,15 +164,61 @@ OCStackResult OCProcess(); * @return ::OC_STACK_OK on success, some other value upon failure. */ OCStackResult OCDoResource(OCDoHandle *handle, - OCMethod method, - const char *requestUri, - const OCDevAddr *destination, - OCPayload* payload, - OCConnectivityType connectivityType, - OCQualityOfService qos, - OCCallbackData *cbData, - OCHeaderOption *options, - uint8_t numOptions); + OCMethod method, + const char *requestUri, + const OCDevAddr *destination, + OCPayload* payload, + OCConnectivityType connectivityType, + OCQualityOfService qos, + OCCallbackData *cbData, + OCHeaderOption *options, + uint8_t numOptions); + +/** + * This function discovers or Perform requests on a specified resource + * (specified by that Resource's respective URI). + * + * @param handle To refer to the request sent out on behalf of + * calling this API. This handle can be used to cancel this operation + * via the OCCancel API. + * @note: This reference is handled internally, and should not be free'd by + * the consumer. A NULL handle is permitted in the event where the caller + * has no use for the return value. + * @param method To perform on the resource. + * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in + * favor of destination.) + * @param destination Complete description of destination. + * @param payload Encoded request payload. + OCDoRequest does not free given payload. + * @param connectivityType Modifier flags when destination is not given. + * @param qos Quality of service. Note that if this API is called on a uri with the + * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS + * since it is impractical to send other QOS levels on such addresses. + * @param cbData Asynchronous callback function that is invoked by the stack when + * discovery or resource interaction is received. The discovery could be + * related to filtered/scoped/particular resource. The callback is + * generated for each response received. + * @param options The address of an array containing the vendor specific header options + * to be sent with the request. + * @param numOptions Number of header options to be included. + * + * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling + * this API again) require the use of the same base URI as the original request to successfully + * amend the presence filters. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult OCDoRequest(OCDoHandle *handle, + OCMethod method, + const char *requestUri, + const OCDevAddr *destination, + OCPayload* payload, + OCConnectivityType connectivityType, + OCQualityOfService qos, + OCCallbackData *cbData, + OCHeaderOption *options, + uint8_t numOptions); + /** * This function cancels a request associated with a specific @ref OCDoResource invocation. * @@ -168,8 +230,10 @@ OCStackResult OCDoResource(OCDoHandle *handle, * * @return ::OC_STACK_OK on success, some other value upon failure. */ -OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options, - uint8_t numOptions); +OCStackResult OCCancel(OCDoHandle handle, + OCQualityOfService qos, + OCHeaderOption * options, + uint8_t numOptions); /** * Register Persistent storage callback. @@ -213,7 +277,7 @@ OCStackResult OCStartPresence(const uint32_t ttl); */ OCStackResult OCStopPresence(); -#endif +#endif // WITH_PRESENCE /** @@ -231,7 +295,13 @@ OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandle /** * This function sets device information. * - * @param deviceInfo Structure passed by the server application containing the device information. + * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default + * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked + * list. The default Device Type is mandatory and always specified by this Device as the first + * Device Type. + * + * @param deviceInfo Structure passed by the server application containing the device + * information. * * @return * ::OC_STACK_OK no errors. @@ -279,7 +349,6 @@ OCStackResult OCCreateResource(OCResourceHandle *handle, void* callbackParam, uint8_t resourceProperties); - /** * This function adds a resource to a collection resource. * @@ -330,8 +399,9 @@ OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle, * * @return ::OC_STACK_OK on success, some other value upon failure. */ -OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler, - void *callbackParameter); +OCStackResult OCBindResourceHandler(OCResourceHandle handle, + OCEntityHandler entityHandler, + void *callbackParameter); /** * This function gets the number of resources that have been created in the stack. @@ -499,10 +569,10 @@ OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService q */ OCStackResult OCNotifyListOfObservers (OCResourceHandle handle, - OCObservationId *obsIdList, - uint8_t numberOfIds, - const OCRepPayload *payload, - OCQualityOfService qos); + OCObservationId *obsIdList, + uint8_t numberOfIds, + const OCRepPayload *payload, + OCQualityOfService qos); /** @@ -547,10 +617,267 @@ const OCDPDev_t* OCGetDirectPairedDevices(); * @param[in] resultCallback Callback fucntion to event status of process. * @return OTM_SUCCESS in case of success and other value otherwise. */ -OCStackResult OCDoDirectPairing(OCDPDev_t* peer, OCPrm_t pmSel, char *pinNumber, - OCDirectPairingCB resultCallback); +OCStackResult OCDoDirectPairing(void *ctx, OCDPDev_t* peer, OCPrm_t pmSel, char *pinNumber, + OCDirectPairingCB resultCallback); + +#ifdef WITH_CHPROXY +/** + * This function sets uri being used for proxy. + * + * @param uri NULL terminated resource uri for CoAP-HTTP Proxy. + */ +OCStackResult OCSetProxyURI(const char *uri); +#endif + +#if defined(RD_CLIENT) || defined(RD_SERVER) +/** + * This function binds an resource unique id to the resource. + * + * @param handle Handle to the resource that the contained resource is to be bound. + * @param ins Unique ID for resource. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult OCBindResourceInsToResource(OCResourceHandle handle, int64_t ins); + +/** + * This function gets the resource unique id for a resource. + * + * @param handle Handle of resource. + * @param ins Unique ID for resource. + * + * @return Ins if resource found or 0 resource not found. + */ +OCStackResult OCGetResourceIns(OCResourceHandle handle, int64_t *ins); + +#endif + +/** +* This function gets a resource handle by resource uri. +* +* @param uri Uri of Resource to get Resource handle. +* +* @return Found resource handle or NULL if not found. +*/ +OCResourceHandle OCGetResourceHandleAtUri(const char *uri); + + +#ifdef RD_SERVER +/** +* Search the RD database for queries. +* +* @param interfaceType is the interface type that is queried. +* @param resourceType is the resource type that is queried. +* @param discPayload is NULL if no resource found or else OCDiscoveryPayload with the details +* about the resource. +* +* @return ::OC_STACK_OK in case of success or else other value. +*/ +OCStackResult OCRDDatabaseCheckResources(const char *interfaceType, const char *resourceType, + OCDiscoveryPayload *discPayload); +#endif //#endif // DIRECT_PAIRING +/** + * Add a header option to the given header option array. + * + * @param ocHdrOpt Pointer to existing options. + * @param numOptions Number of existing options. + * @param optionID COAP option ID. + * @param optionData Option data value. + * @param optionDataLength Size of Option data value. + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult +OCSetHeaderOption(OCHeaderOption* ocHdrOpt, + size_t* numOptions, + uint16_t optionID, + void* optionData, + size_t optionDataLength); + +/** + * Get data value of the option with specified option ID from given header option array. + * + * @param ocHdrOpt Pointer to existing options. + * @param numOptions Number of existing options. + * @param optionID COAP option ID. + * @param optionData Pointer to option data. + * @param optionDataLength Size of option data value. + * @param receivedDatalLength Pointer to the actual length of received data. + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult +OCGetHeaderOption(OCHeaderOption* ocHdrOpt, + size_t numOptions, + uint16_t optionID, + void* optionData, + size_t optionDataLength, + uint16_t* receivedDatalLength); + +/** + * gets the deviceId of the client + * + * @param deviceId pointer. + * @return Returns ::OC_STACK_OK if success. + */ +OCStackResult OCGetDeviceId(OCUUIdentity *deviceId); + +/** + * sets the deviceId of the client + * + * @param deviceId pointer. + * @return Returns ::OC_STACK_OK if success. + */ +OCStackResult OCSetDeviceId(const OCUUIdentity *deviceId); + + /** + * Gets the bool state of "isOwned" property on the doxm resource. + * + * @param isOwned a pointer to be assigned to isOwned property + * @return Returns ::OC_STACK_OK if success. + */ +OCStackResult OCGetDeviceOwnedState(bool *isOwned); + +/** + * Encode an address string to match RFC 6874. + * + * @param outputAddress a char array to be written with the encoded string. + * + * @param outputSize size of outputAddress buffer. + * + * @param inputAddress a char array of size <= CA_MAX_URI_LENGTH + * containing a valid IPv6 address string. + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult OCEncodeAddressForRFC6874(char* outputAddress, + size_t outputSize, + const char* inputAddress); + +/** + * Decode an address string according to RFC 6874. + * + * @param outputAddress a char array to be written with the decoded string. + * + * @param outputSize size of outputAddress buffer. + * + * @param inputAddress a valid percent-encoded address string. + * + * @param end NULL if the entire entire inputAddress is a null-terminated percent- + * encoded address string. Otherwise, a pointer to the first byte that + * is not part of the address string (e.g., ']' in a URI). + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult OCDecodeAddressForRFC6874(char* outputAddress, + size_t outputSize, + const char* inputAddress, + const char* end); + +/** + * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for + * all OCF defined properties. + * + * @param type the payload type for device and platform as defined in @ref OCPayloadType. + * @param propName the pre-defined property as per OCF spec. + * @param value the value of the property to be set. + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value); + +/** + * Get the value of /oic/d and /oic/p properties. This function is a generic function that get value + * for all OCF defined properties. + * + * @param type the payload type for device and platform as defined in @ref OCPayloadType. + * @param propName the pre-defined as per OCF spec. + * @param value this holds the return value. In case of error will be set to NULL. + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult OCGetPropertyValue(OCPayloadType type, const char *propName, void **value); + +/** +* Delete client callback info all. +*/ +void OCClearCallBackList(); + +/** + * Delete observer info all. + */ +void OCClearObserverlist(); + +/** + * API to encrypt the un-encrypted DB file before OCRegisterPersistentStorageHandler + * If the API is successful, un-encrypted file will be removed, and if the encrypted file + * is currupted, then it restores encrypted file using rescue file. + * + * @param[in] key key used for encryption + * @param[in] psPlain OCPersistentStorage for the plain DB + * @param[in] psEnc OCPersistentStorage for the encrypted DB + * @param[in] psRescue OCPersistentStorage for the rescue DB + * + * @return ::OC_STACK_OK on success and other value otherwise. + */ +OCStackResult OCSetSecurePSI(const unsigned char *key, const OCPersistentStorage *psPlain, + const OCPersistentStorage *psEnc, const OCPersistentStorage *psRescue); + +/** + * Generic Encryption function to encrypt data buffer in pt + * and update in ct and len in ct_len. (AES-CBC-HMAC) + * + * @param[in] pt plaintext to be encrypted + * @param[in] pt_len length of plaintext + * @param[out] ct ciphered text + * @param[out] ct_len is length of the ciphered text. + * + * @return ::0 for Success. + */ +int OCEncrypt(const unsigned char *pt, size_t pt_len, + unsigned char **ct, size_t *ct_len); + +/** + * Generic Decryption fucntion to decrypt data buffer in ct + * and update in pt and len in pt_len. (AES-CBC-HMAC) + * + * @param[in] ct ciphered to be decrypted + * @param[in] ct_len length of cipher text + * @param[out] pt plaintext text + * @param[out] pt_len is length of the palintext text. + * + * @return ::0 for Success. + */ +int OCDecrypt(const unsigned char *ct, size_t ct_len, + unsigned char **pt, size_t *pt_len); + +/** + * API to set key to psi + * + * @param[in] key key used for encryption + * @return ::OC_STACK_OK for Success, otherwise some error value. + */ +OCStackResult OCSetKey(const unsigned char* key); + +/** + * API to get key from psi + * + * @param[out] key key used for encryption + * @return ::OC_STACK_OK for Success, otherwise some error value. + */ +OCStackResult OCGetKey(unsigned char* key); + +/** + * API to register OTM event handler + * + * @param[in] ctx user context returned in the callback + * @param[in] cb callback function to receive the OTM event on server side + * @return ::OC_STACK_OK for Success, otherwise some error value. + */ +OCStackResult OCSetOtmEventHandler(void *ctx, OCOtmEventHandler cb); + #ifdef __cplusplus } #endif // __cplusplus