1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
25 * This file contains APIs for OIC Stack to be implemented.
39 /** Macro to use Random port.*/
40 #define USE_RANDOM_PORT (0)
47 * This function Initializes the OC Stack. Must be called prior to starting the stack.
49 * @param mode OCMode Host device is client, server, or client-server.
50 * @param serverFlags OCTransportFlags Default server transport flags.
51 * @param clientFlags OCTransportFlags Default client transport flags.
53 * @return ::OC_STACK_OK on success, some other value upon failure.
55 OCStackResult OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
58 * This function Initializes the OC Stack. Must be called prior to starting the stack.
60 * @param ipAddr IP Address of host device. Deprecated parameter.
61 * @param port Port of host device. Deprecated parameter.
62 * @param mode OCMode Host device is client, server, or client-server.
64 * @return ::OC_STACK_OK on success, some other value upon failure.
66 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
70 * @brief Set Remote Access information for XMPP Client.
71 * @param raInfo [IN] remote access info.
73 * @return ::OC_STACK_OK on success, some other value upon failure.
75 OCStackResult OCSetRAInfo(const OCRAInfo_t *raInfo);
79 * This function Stops the OC stack. Use for a controlled shutdown.
81 * @note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
82 * all resources this server is hosting. OCDeleteResource() performs operations similar to
83 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
86 * @return ::OC_STACK_OK on success, some other value upon failure.
88 OCStackResult OCStop();
91 * This function starts receiving the multicast traffic. This can be only called
92 * when stack is in OC_STACK_INITIALIZED state but device is not receiving multicast
95 * @return ::OC_STACK_OK on success, some other value upon failure.
97 OCStackResult OCStartMulticastServer();
100 * This function stops receiving the multicast traffic. The rest of the stack
101 * keeps working and no resource are deleted. Device can still receive the unicast
102 * traffic. Once this is set, no response to multicast /oic/res will be sent by the
103 * device. This is to be used for devices that uses other entity to push resources.
105 * @return ::OC_STACK_OK on success, some other value upon failure.
107 OCStackResult OCStopMulticastServer();
110 * This function is Called in main loop of OC client or server.
111 * Allows low-level processing of stack services.
113 * @return ::OC_STACK_OK on success, some other value upon failure.
115 OCStackResult OCProcess();
118 * This function discovers or Perform requests on a specified resource
119 * (specified by that Resource's respective URI).
121 * @param handle To refer to the request sent out on behalf of
122 * calling this API. This handle can be used to cancel this operation
123 * via the OCCancel API.
124 * @note: This reference is handled internally, and should not be free'd by
125 * the consumer. A NULL handle is permitted in the event where the caller
126 * has no use for the return value.
127 * @param method To perform on the resource.
128 * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in
129 * favor of destination.)
130 * @param destination Complete description of destination.
131 * @param payload Encoded request payload.
132 * @param connectivityType Modifier flags when destination is not given.
133 * @param qos Quality of service. Note that if this API is called on a uri with the
134 * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
135 * since it is impractical to send other QOS levels on such addresses.
136 * @param cbData Asynchronous callback function that is invoked by the stack when
137 * discovery or resource interaction is received. The discovery could be
138 * related to filtered/scoped/particular resource. The callback is
139 * generated for each response received.
140 * @param options The address of an array containing the vendor specific header options
141 * to be sent with the request.
142 * @param numOptions Number of header options to be included.
144 * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
145 * this API again) require the use of the same base URI as the original request to successfully
146 * amend the presence filters.
148 * @return ::OC_STACK_OK on success, some other value upon failure.
150 OCStackResult OCDoResource(OCDoHandle *handle,
152 const char *requestUri,
153 const OCDevAddr *destination,
155 OCConnectivityType connectivityType,
156 OCQualityOfService qos,
157 OCCallbackData *cbData,
158 OCHeaderOption *options,
161 * This function cancels a request associated with a specific @ref OCDoResource invocation.
163 * @param handle Used to identify a specific OCDoResource invocation.
164 * @param qos Used to specify Quality of Service(read below).
165 * @param options Used to specify vendor specific header options when sending
166 * explicit observe cancellation.
167 * @param numOptions Number of header options to be included.
169 * @return ::OC_STACK_OK on success, some other value upon failure.
171 OCStackResult OCCancel(OCDoHandle handle,
172 OCQualityOfService qos,
173 OCHeaderOption * options,
177 * Register Persistent storage callback.
178 * @param persistentStorageHandler Pointers to open, read, write, close & unlink handlers.
181 * OC_STACK_OK No errors; Success.
182 * OC_STACK_INVALID_PARAM Invalid parameter.
184 OCStackResult OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
188 * When operating in OCServer or OCClientServer mode,
189 * this API will start sending out presence notifications to clients via multicast.
190 * Once this API has been called with a success, clients may query for this server's presence and
191 * this server's stack will respond via multicast.
193 * Server can call this function when it comes online for the first time, or when it comes back
194 * online from offline mode, or when it re enters network.
196 * @param ttl Time To Live in seconds.
197 * @note: If ttl is '0', then the default stack value will be used (60 Seconds).
198 * If ttl is greater than ::OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be
199 * set to ::OC_MAX_PRESENCE_TTL_SECONDS.
201 * @return ::OC_STACK_OK on success, some other value upon failure.
203 OCStackResult OCStartPresence(const uint32_t ttl);
206 * When operating in OCServer or OCClientServer mode, this API will stop sending
207 * out presence notifications to clients via multicast.
208 * Once this API has been called with a success this server's stack will not respond to clients
209 * querying for this server's presence.
211 * Server can call this function when it is terminating, going offline, or when going
214 * @return ::OC_STACK_OK on success, some other value upon failure.
217 OCStackResult OCStopPresence();
222 * This function sets default device entity handler.
224 * @param entityHandler Entity handler function that is called by ocstack to handle requests
225 * for any undefined resources or default actions.If NULL is passed it
226 * removes the device default entity handler.
227 * @param callbackParameter Parameter passed back when entityHandler is called.
229 * @return ::OC_STACK_OK on success, some other value upon failure.
231 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler, void* callbackParameter);
234 * This function sets device information.
236 * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default
237 * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked
238 * list. The default Device Type is mandatory and always specified by this Device as the first
241 * @param deviceInfo Structure passed by the server application containing the device
245 * ::OC_STACK_OK no errors.
246 * ::OC_STACK_INVALID_PARAM invalid parameter.
247 * ::OC_STACK_ERROR stack process error.
249 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
252 * This function sets platform information.
254 * @param platformInfo Structure passed by the server application containing
255 * the platform information.
259 * ::OC_STACK_OK no errors.
260 * ::OC_STACK_INVALID_PARAM invalid parameter.
261 * ::OC_STACK_ERROR stack process error.
263 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
266 * This function creates a resource.
268 * @param handle Pointer to handle to newly created resource. Set by ocstack and
269 * used to refer to resource.
270 * @param resourceTypeName Name of resource type. Example: "core.led".
271 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
272 * @param uri URI of the resource. Example: "/a/led".
273 * @param entityHandler Entity handler function that is called by ocstack to handle
275 * NULL for default entity handler.
276 * @param callbackParam parameter passed back when entityHandler is called.
277 * @param resourceProperties Properties supported by resource.
278 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
280 * @return ::OC_STACK_OK on success, some other value upon failure.
282 OCStackResult OCCreateResource(OCResourceHandle *handle,
283 const char *resourceTypeName,
284 const char *resourceInterfaceName,
286 OCEntityHandler entityHandler,
288 uint8_t resourceProperties);
291 * This function adds a resource to a collection resource.
293 * @param collectionHandle Handle to the collection resource.
294 * @param resourceHandle Handle to resource to be added to the collection resource.
296 * @return ::OC_STACK_OK on success, some other value upon failure.
298 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
301 * This function removes a resource from a collection resource.
303 * @param collectionHandle Handle to the collection resource.
304 * @param resourceHandle Handle to resource to be removed from the collection resource.
306 * @return ::OC_STACK_OK on success, some other value upon failure.
308 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
311 * This function binds a resource type to a resource.
313 * @param handle Handle to the resource.
314 * @param resourceTypeName Name of resource type. Example: "core.led".
316 * @return ::OC_STACK_OK on success, some other value upon failure.
318 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
319 const char *resourceTypeName);
321 * This function binds a resource interface to a resource.
323 * @param handle Handle to the resource.
324 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
326 * @return ::OC_STACK_OK on success, some other value upon failure.
328 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
329 const char *resourceInterfaceName);
332 * This function binds an entity handler to the resource.
334 * @param handle Handle to the resource that the contained resource is to be bound.
335 * @param entityHandler Entity handler function that is called by ocstack to handle requests.
336 * @param callbackParameter Context parameter that will be passed to entityHandler.
338 * @return ::OC_STACK_OK on success, some other value upon failure.
340 OCStackResult OCBindResourceHandler(OCResourceHandle handle,
341 OCEntityHandler entityHandler,
342 void *callbackParameter);
345 * This function gets the number of resources that have been created in the stack.
347 * @param numResources Pointer to count variable.
349 * @return ::OC_STACK_OK on success, some other value upon failure.
351 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
354 * This function gets a resource handle by index.
356 * @param index Index of resource, 0 to Count - 1.
358 * @return Found resource handle or NULL if not found.
360 OCResourceHandle OCGetResourceHandle(uint8_t index);
363 * This function deletes resource specified by handle. Deletes resource and all
364 * resource type and resource interface linked lists.
366 * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
367 * client observers that "this" resource is being deleted.
369 * @param handle Handle of resource to be deleted.
371 * @return ::OC_STACK_OK on success, some other value upon failure.
373 OCStackResult OCDeleteResource(OCResourceHandle handle);
376 * Get a string representation the server instance ID.
377 * The memory is managed internal to this function, so freeing externally will result
378 * in a runtime error.
379 * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
380 * This is done automatically during the OCInit process,
381 * so ensure that this call is done after that.
383 * @return A string representation the server instance ID.
385 const char* OCGetServerInstanceIDString(void);
388 * This function gets the URI of the resource specified by handle.
390 * @param handle Handle of resource.
392 * @return URI string if resource found or NULL if not found.
394 const char *OCGetResourceUri(OCResourceHandle handle);
397 * This function gets the properties of the resource specified by handle.
399 * @param handle Handle of resource.
401 * @return OCResourceProperty Bitmask or -1 if resource is not found.
403 * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
406 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
409 * This function gets the number of resource types of the resource.
411 * @param handle Handle of resource.
412 * @param numResourceTypes Pointer to count variable.
414 * @return ::OC_STACK_OK on success, some other value upon failure.
416 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
419 * This function gets name of resource type of the resource.
421 * @param handle Handle of resource.
422 * @param index Index of resource, 0 to Count - 1.
424 * @return Resource type name if resource found or NULL if resource not found.
426 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
429 * This function gets the number of resource interfaces of the resource.
431 * @param handle Handle of resource.
432 * @param numResourceInterfaces Pointer to count variable.
434 * @return ::OC_STACK_OK on success, some other value upon failure.
436 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
437 uint8_t *numResourceInterfaces);
440 * This function gets name of resource interface of the resource.
442 * @param handle Handle of resource.
443 * @param index Index of resource, 0 to Count - 1.
445 * @return Resource interface name if resource found or NULL if resource not found.
447 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
450 * This function gets methods of resource interface of the resource.
452 * @param handle Handle of resource.
453 * @param index Index of resource, 0 to Count - 1.
455 * @return Allowed methods if resource found or NULL if resource not found.
457 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
460 * This function gets resource handle from the collection resource by index.
462 * @param collectionHandle Handle of collection resource.
463 * @param index Index of contained resource, 0 to Count - 1.
465 * @return Handle to contained resource if resource found or NULL if resource not found.
467 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
471 * This function gets the entity handler for a resource.
473 * @param handle Handle of resource.
475 * @return Entity handler if resource found or NULL resource not found.
477 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
480 * This function notify all registered observers that the resource representation has
481 * changed. If observation includes a query the client is notified only if the query is valid after
482 * the resource representation has changed.
484 * @param handle Handle of resource.
485 * @param qos Desired quality of service for the observation notifications.
487 * @return ::OC_STACK_OK on success, some other value upon failure.
489 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
492 * Notify specific observers with updated value of representation.
493 * Before this API is invoked by entity handler it has finished processing
494 * queries for the associated observers.
496 * @param handle Handle of resource.
497 * @param obsIdList List of observation IDs that need to be notified.
498 * @param numberOfIds Number of observation IDs included in obsIdList.
499 * @param payload Object representing the notification
500 * @param qos Desired quality of service of the observation notifications.
502 * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
503 * The maximum size of the notification is 1015 bytes for non-Arduino platforms. For Arduino
504 * the maximum size is 247 bytes.
506 * @return ::OC_STACK_OK on success, some other value upon failure.
509 OCNotifyListOfObservers (OCResourceHandle handle,
510 OCObservationId *obsIdList,
512 const OCRepPayload *payload,
513 OCQualityOfService qos);
517 * This function sends a response to a request.
518 * The response can be a normal, slow, or block (i.e. a response that
519 * is too large to be sent in a single PDU and must span multiple transmissions).
521 * @param response Pointer to structure that contains response parameters.
523 * @return ::OC_STACK_OK on success, some other value upon failure.
525 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
527 //#ifdef DIRECT_PAIRING
529 * The function is responsible for discovery of direct-pairing device is current subnet. It will list
530 * all the device in subnet which support direct-pairing.
531 * Caller must NOT free returned constant pointer
533 * @param[in] timeout Timeout in seconds, value till which function will listen to responses from
534 * client before returning the list of devices.
535 * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
537 const OCDPDev_t* OCDiscoverDirectPairingDevices(unsigned short waittime);
540 * The function is responsible for return of paired device list via direct-pairing. It will list
541 * all the device which is previousely paired with client.
542 * Caller must NOT free returned constant pointer
544 * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
546 const OCDPDev_t* OCGetDirectPairedDevices();
549 * The function is responsible for establishment of direct-pairing. It will proceed mode negotiation
550 * and connect PIN based dtls session.
552 * @param[in] peer Target device to establish direct-pairing.
553 * @param[in] pmSel Selected mode of pairing.
554 * @param[in] pinNumber PIN number for authentication, pin lenght is defined DP_PIN_LENGTH(8).
555 * @param[in] resultCallback Callback fucntion to event status of process.
556 * @return OTM_SUCCESS in case of success and other value otherwise.
558 OCStackResult OCDoDirectPairing(void *ctx, OCDPDev_t* peer, OCPrm_t pmSel, char *pinNumber,
559 OCDirectPairingCB resultCallback);
563 * This function sets uri being used for proxy.
565 * @param uri NULL terminated resource uri for CoAP-HTTP Proxy.
567 OCStackResult OCSetProxyURI(const char *uri);
570 #if defined(RD_CLIENT) || defined(RD_SERVER)
572 * This function binds an resource unique id to the resource.
574 * @param handle Handle to the resource that the contained resource is to be bound.
575 * @param ins Unique ID for resource.
577 * @return ::OC_STACK_OK on success, some other value upon failure.
579 OCStackResult OCBindResourceInsToResource(OCResourceHandle handle, uint8_t ins);
582 * This function gets the resource unique id for a resource.
584 * @param handle Handle of resource.
585 * @param ins Unique ID for resource.
587 * @return Ins if resource found or 0 resource not found.
589 OCStackResult OCGetResourceIns(OCResourceHandle handle, uint8_t *ins);
594 * This function gets a resource handle by resource uri.
596 * @param uri Uri of Resource to get Resource handle.
598 * @return Found resource handle or NULL if not found.
600 OCResourceHandle OCGetResourceHandleAtUri(const char *uri);
605 * Search the RD database for queries.
607 * @param interfaceType is the interface type that is queried.
608 * @param resourceType is the resource type that is queried.
609 * @param discPayload is NULL if no resource found or else OCDiscoveryPayload with the details
610 * about the resource.
612 * @return ::OC_STACK_OK in case of success or else other value.
614 OCStackResult OCRDDatabaseCheckResources(const char *interfaceType, const char *resourceType,
615 OCDiscoveryPayload *discPayload);
617 //#endif // DIRECT_PAIRING
620 * Add a header option to the given header option array.
622 * @param ocHdrOpt Pointer to existing options.
623 * @param numOptions Number of existing options.
624 * @param optionID COAP option ID.
625 * @param optionData Option data value.
626 * @param optionDataLength Size of Option data value.
628 * @return ::OC_STACK_OK on success and other value otherwise.
631 OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
635 size_t optionDataLength);
638 * Get data value of the option with specified option ID from given header option array.
640 * @param ocHdrOpt Pointer to existing options.
641 * @param numOptions Number of existing options.
642 * @param optionID COAP option ID.
643 * @param optionData Pointer to option data.
644 * @param optionDataLength Size of option data value.
645 * @param receivedDatalLength Pointer to the actual length of received data.
647 * @return ::OC_STACK_OK on success and other value otherwise.
650 OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
654 size_t optionDataLength,
655 uint16_t* receivedDatalLength);
658 * gets the deviceId of the client
660 * @param deviceId pointer.
661 * @return Returns ::OC_STACK_OK if success.
663 OCStackResult OCGetDeviceId(OCUUIdentity *deviceId);
666 * sets the deviceId of the client
668 * @param deviceId pointer.
669 * @return Returns ::OC_STACK_OK if success.
671 OCStackResult OCSetDeviceId(const OCUUIdentity *deviceId);
674 * Encode an address string to match RFC 6874.
676 * @param outputAddress a char array to be written with the encoded string.
678 * @param outputSize size of outputAddress buffer.
680 * @param inputAddress a char array of size <= CA_MAX_URI_LENGTH
681 * containing a valid IPv6 address string.
683 * @return ::OC_STACK_OK on success and other value otherwise.
685 OCStackResult OCEncodeAddressForRFC6874(char* outputAddress,
687 const char* inputAddress);
690 * Decode an address string according to RFC 6874.
692 * @param outputAddress a char array to be written with the decoded string.
694 * @param outputSize size of outputAddress buffer.
696 * @param inputAddress a valid percent-encoded address string.
698 * @param end NULL if the entire entire inputAddress is a null-terminated percent-
699 * encoded address string. Otherwise, a pointer to the first byte that
700 * is not part of the address string (e.g., ']' in a URI).
702 * @return ::OC_STACK_OK on success and other value otherwise.
704 OCStackResult OCDecodeAddressForRFC6874(char* outputAddress,
706 const char* inputAddress,
710 * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for
711 * all OCF defined properties.
713 * @param type the payload type for device and platform as defined in @ref OCPayloadType.
714 * @param propName the pre-defined property as per OCF spec.
715 * @param value the value of the property to be set.
717 * @return ::OC_STACK_OK on success and other value otherwise.
719 OCStackResult OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
722 * Get the value of /oic/d and /oic/p properties. This function is a generic function that get value
723 * for all OCF defined properties.
725 * @param type the payload type for device and platform as defined in @ref OCPayloadType.
726 * @param propName the pre-defined as per OCF spec.
727 * @param value this holds the return value. In case of error will be set to NULL.
729 * @return ::OC_STACK_OK on success and other value otherwise.
731 OCStackResult OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
735 #endif // __cplusplus
737 #endif /* OCSTACK_H_ */