#ifndef OC_OBSERVE_H
#define OC_OBSERVE_H
-/* Sequence number is a 24 bit field */
+// Sequence number is a 24 bit field, per
+// https://tools.ietf.org/html/draft-ietf-core-observe-16
#define MAX_SEQUENCE_NUMBER (0xFFFFFF)
#define MAX_OBSERVER_FAILED_COMM (2)
#define MAX_OBSERVER_NON_COUNT (3)
-/* This information is stored for each registerd observer */
+/**
+ * This information is stored for each registered observer.
+ */
typedef struct ResourceObserver
{
// Observation Identifier for request
} ResourceObserver;
#ifdef WITH_PRESENCE
+/**
+ * Create an observe response and send to all observers in the observe list.
+ *
+ * @param method RESTful method.
+ * @param resPtr Observed resource.
+ * @param maxAge Time To Live (in seconds) of observation.
+ * @param resourceType Resource type. Allows resource type name to be added to response.
+ * @param qos Quality of service of resource.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
OCResourceType *resourceType, OCQualityOfService qos);
#else
+/**
+ * Create an observe response and send to all observers in the observe list.
+ *
+ * @param method RESTful method.
+ * @param resPtr Observed resource.
+ * @param maxAge Time To Live (in seconds) of observation.
+ * @param qos Quality of service of resource.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
OCQualityOfService qos);
#endif
+
+/**
+ * Notify specific observers with updated value of representation.
+ *
+ * @param resource Observed resource
+ * @param obsIdList List of observation ids that need to be notified.
+ * @param numberOfIds Number of observation ids included in obsIdList.
+ * @param notificationJSONPayload - JSON encoded payload to send in notification.
+ * @param maxAge Time To Live (in seconds) of observation.
+ * @param qos Desired quality of service of the observation notifications.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult SendListObserverNotification (OCResource * resource,
OCObservationId *obsIdList, uint8_t numberOfIds,
const char *notificationJSONPayload, uint32_t maxAge,
OCQualityOfService qos);
+/**
+ * Delete all observers in the observe list.
+ */
void DeleteObserverList();
+/**
+ * Create a unique observation ID.
+ *
+ * @param observationId Pointer to generated ID.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult GenerateObserverId (OCObservationId *observationId);
+/**
+ * Add observer for a resource.
+ *
+ * @param resUri Resource URI string.
+ * @param query Query string.
+ * @param obsId Observation ID.
+ * @param token Request token.
+ * @param tokenLength Length of token.
+ * @param resHandle Resource handle.
+ * @param qos Quality of service of observation.
+ * @param addressInfo Address of observer.
+ * @param connectivityType Connection type.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult AddObserver (const char *resUri,
const char *query,
OCObservationId obsId,
const CAAddress_t *addressInfo,
CAConnectivityType_t connectivityType);
+/**
+ * Delete observer with specified token from list of observers.
+ * Free memory that was allocated for the observer in the list.
+ *
+ * @param token Token to search for.
+ * @param tokenLength Length of token.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult DeleteObserverUsingToken (CAToken_t * token, uint8_t tokenLength);
+/**
+ * Search the list of observers for the specified token.
+ *
+ * @param token Token to search for.
+ * @param tokenLength Length of token.
+ *
+ * @return Pointer to found observer.
+ */
ResourceObserver* GetObserverUsingToken (const CAToken_t * token, uint8_t tokenLength);
+/**
+ * Search the list of observers for the specified observe ID.
+ *
+ * @param observeId Observer ID to search for
+ *
+ * @return Pointer to found observer.
+ */
ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
+/**
+ * Add observe header option to a request.
+ *
+ * @param caHdrOpt Target request CA header option.
+ * @param ocHdrOpt Pointer to existing options.
+ * @param numOptions Number of existing options.
+ * @param observeFlag Register/de-register observation. Should be either
+ * ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult
CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
OCHeaderOption *ocHdrOpt,
uint8_t numOptions,
uint8_t observeFlag);
+
+/**
+ * Copy the observe option from a received request
+ *
+ * @param observationOption Pointer to observe option value. Should be either
+ * ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or ::OC_OBSERVE_NO_OPTION if observe not found.
+ *
+ * @param options Options in received request. Observe option is removed if found.
+ * @param numOptions Number of options in the received request. Decremented if observe option is
+ * extracted.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
OCStackResult
GetObserveHeaderOption (uint32_t * observationOption,
CAHeaderOption_t *options,
OCStackResult result;
} OCObserveReq;
-// following structure will be created in occoap and passed up the stack on the server side
+/**
+ * This structure will be created in occoap and passed up the stack on the server side.
+ */
typedef struct
{
// Observe option field
char * resourceUri;
} OCServerProtocolResponse;
-// following structure will be created in occoap and passed up the stack on the client side
+/**
+ * This structure will be created in occoap and passed up the stack on the client side.
+ */
typedef struct
{
// handle is retrieved by comparing the token-handle pair in the PDU.
OCClientResponse * clientResponse;
} OCResponse;
-// following typedef is to represent our Server Instance identification.
+/**
+ * This typedef is to represent our Server Instance identification.
+ */
typedef uint32_t ServerID;
//-----------------------------------------------------------------------------
#ifdef WITH_PRESENCE
/**
- * Notify Presence subscribers that a resource has been modified
+ * Notify Presence subscribers that a resource has been modified.
*
- * @param resourceType - Handle to the resourceType linked list of resource
- * that was modified.
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @param resourceType Handle to the resourceType linked list of resource
+ * that was modified.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult SendPresenceNotification(OCResourceType *resourceType);
+
/**
- * Send Stop Notification to Presence subscribers
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * Send Stop Notification to Presence subscribers.
*
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult SendStopNotification();
#endif // WITH_PRESENCE
/**
- * Bind a resource interface to a resource
+ * Bind a resource interface to a resource.
*
- * @param resource - target resource
- * @param resourceInterfaceName - resource interface
- * @return
- * OCStackResult
+ * @param resource Target resource.
+ * @param resourceInterfaceName Resource interface.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult BindResourceInterfaceToResource(OCResource* resource,
const char *resourceInterfaceName);
/**
- * Bind a resourcetype to a resource
+ * Bind a resourcetype to a resource.
*
- * @param resource - target resource
- * @param resourceTypeName - resourcetype
- * @return
- * OCStackResult
+ * @param resource Target resource.
+ * @param resourceTypeName Name of resource type.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult BindResourceTypeToResource(OCResource* resource,
const char *resourceTypeName);
+
+// Converts a CAResult_t type to a OCStackResult type.
/**
- * Finds a resource type in an OCResourceType link-list.
- *
- * @param resourceTypeList - the link-list to be searched through
- * @param resourceTypeName - the key to search for
+ * Converts a CAResult_t type to a OCStackResult type.
*
- * @return
- * resourceType that matches the key (ie. resourceTypeName)
- * NULL - either an invalid parameter or this function was unable to find the key.
+ * @param caResult CAResult_t value to convert
+ * @return OCStackResult that was converted from the input CAResult_t value.
*/
-OCResourceType *findResourceType(OCResourceType * resourceTypeList, const char * resourceTypeName);
-
-// returns the internal representation of the server instance ID.
-// Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
-// This is done automatically during the OCInit process (via the call to OCInitCoAP),
-// so ensure that this call is done after that.
-const ServerID OCGetServerInstanceID(void);
-
-// Converts a CAResult_t type to a OCStackResult type.
OCStackResult CAResultToOCResult(CAResult_t caResult);
-// returns a string representation the server instance ID.
-// The memory is managed internal to this function, so freeing externally will result
-// in a compiler error
-// Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
-// This is done automatically during the OCInit process (via the call to OCInitCoAP),
-// so ensure that this call is done after that.
+/**
+ * Get a string representation the server instance ID.
+ * The memory is managed internal to this function, so freeing externally will result
+ * in a compiler error
+ * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
+ * This is done automatically during the OCInit process (via the call to OCInitCoAP),
+ * so ensure that this call is done after that.
+ *
+ * @return A string representation the server instance ID.
+ */
const char* OCGetServerInstanceIDString(void);
/**
- * Map OCQualityOfService to CAMessageType
- *
- * @param OCQualityOfService - Input qos.
+ * Map OCQualityOfService to CAMessageType.
*
- * Returns CA message type for a given qos.
+ * @param qos Input qos.
+ * @return CA message type for a given qos.
*/
CAMessageType_t qualityOfServiceToMessageType(OCQualityOfService qos);
#ifdef WITH_PRESENCE
/**
- * Enable/disable a resource property
+ * Enable/disable a resource property.
*
- * @param inputProperty - pointer to resource property
- * @param resourceProperties - property to be enabled/disabled
- * @param enable - 0:disable, 1:enable
+ * @param inputProperty Pointer to resource property.
+ * @param resourceProperties Property to be enabled/disabled.
+ * @param enable 0:disable, 1:enable.
*
- * @return
- * OCStackResult
+ * @return OCStackResult that was converted from the input CAResult_t value.
*/
//TODO: should the following function be public?
OCStackResult OCChangeResourceProperty(OCResourceProperty * inputProperty,
// Typedefs
//-----------------------------------------------------------------------------
-
/**
- * Data structure to encapsulate IPv4/IPv6/Contiki/lwIP device addresses
- *
+ * Data structure to encapsulate IPv4/IPv6/Contiki/lwIP device addresses.
*/
typedef struct OCDevAddr
{
- uint32_t size; /**< length of the address stored in addr field. */
- uint8_t addr[DEV_ADDR_SIZE_MAX]; /**< device address. */
+ uint32_t size; // length of the address stored in addr field.
+ uint8_t addr[DEV_ADDR_SIZE_MAX]; // device address.
} OCDevAddr;
/**
- * OC Virtual resources supported by every OC device
+ * OC Virtual resources supported by every OC device.
*/
typedef enum
{
} OCVirtualResources;
/**
- * Standard RESTful HTTP Methods
+ * Standard RESTful HTTP Methods.
*/
typedef enum
{
} OCMethod;
/**
- * Host Mode of Operation
+ * Host Mode of Operation.
*/
typedef enum
{
} OCMode;
/**
- * Quality of Service
+ * Quality of Service.
*/
typedef enum
{
} OCQualityOfService;
/**
- * Resource Properties
+ * Resource Properties.
*
- * OC_ACTIVE - When this bit is set, the resource is initialized, otherwise the resource
+ * ::OC_ACTIVE When this bit is set, the resource is initialized, otherwise the resource
* is 'inactive'. 'inactive' signifies that the resource has been marked for
* deletion or is already deleted.
- * OC_DISCOVERABLE - When this bit is set, the resource is allowed to be discovered by clients.
- * OC_OBSERVABLE - When this bit is set, the resource is allowed to be observed by clients.
- * OC_SLOW - When this bit is set, the resource has been marked as 'slow'. 'slow' signifies
+ * ::OC_DISCOVERABLE When this bit is set, the resource is allowed to be discovered by clients.
+ * ::OC_OBSERVABLE When this bit is set, the resource is allowed to be observed by clients.
+ * ::OC_SLOW When this bit is set, the resource has been marked as 'slow'. 'slow' signifies
* that responses from this resource can expect delays in processing its
* requests from clients.
- * OC_SECURE - When this bit is set, the resource is a secure resource.
+ * ::OC_SECURE When this bit is set, the resource is a secure resource.
*/
typedef enum
{
} OCResourceProperty;
/**
- * Transport Protocol IDs
+ * Transport Protocol IDs.
*/
typedef enum
{
} OCTransportProtocolID;
/**
- * Adaptor types
+ * Adaptor types.
*/
typedef enum
{
OC_WIFI,
OC_EDR,
OC_LE,
- OC_ALL //Multicast message: send over all the interfaces.
+ OC_ALL // Multicast message: send over all the interfaces.
} OCConnectivityType;
/**
- * Declares Stack Results & Errors
+ * Declares Stack Results & Errors.
*/
typedef enum
{
typedef uint8_t OCObservationId;
/**
- * Action associated with observation
+ * Action associated with observation.
*/
typedef enum
{
} OCObservationInfo;
/**
- * Possible returned values from entity handler
+ * Possible returned values from entity handler.
*/
typedef enum
{
OC_EH_FORBIDDEN
} OCEntityHandlerResult;
-// following structure will be used to define the vendor specific header options to be included
-// in communication packets
-
+/**
+ * This structure will be used to define the vendor specific header options to be included
+ * in communication packets.
+ */
typedef struct OCHeaderOption
{
// The protocol ID this option applies to
} OCClientResponse;
/**
- * Following structure describes the device properties. All non-Null properties will be included
+ * This structure describes the device properties. All non-Null properties will be included
* in a device discovery request.
*/
typedef struct
OC_OBSERVE_FLAG = (1 << 2)
} OCEntityHandlerFlag; //entity_handler_flag_t ;
-// possible returned values from client application
+/**
+ * Possible returned values from client application.
+ */
typedef enum
{
- OC_STACK_DELETE_TRANSACTION = 0,
- OC_STACK_KEEP_TRANSACTION
+ OC_STACK_DELETE_TRANSACTION = 0,//!< OC_STACK_DELETE_TRANSACTION
+ OC_STACK_KEEP_TRANSACTION //!< OC_STACK_KEEP_TRANSACTION
} OCStackApplicationResult;
//-----------------------------------------------------------------------------
/**
* Client applications using a context pointer implement this callback to delete the
- * context upon removal of the callback/context pointer from the internal callback-list
+ * context upon removal of the callback/context pointer from the internal callback-list.
*/
typedef void (* OCClientContextDeleter)(void *context);
/*
- * This info is passed from application to OC Stack when initiating a request to Server
+ * This info is passed from application to OC Stack when initiating a request to Server.
*/
typedef struct
{
(OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
/**
- * Device Entity handler need to use this call back instead of OCEntityHandler
+ * Device Entity handler need to use this call back instead of OCEntityHandler.
*/
typedef OCEntityHandlerResult (*OCDeviceEntityHandler)
(OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest, char* uri);
* @param port
* Port of host device. Deprecated parameter.
* @param mode
- * Host device is client, server, or client-server
+ * Host device is client, server, or client-server.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack init error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
* OCNotifyAllObservers() to notify all client observers that the respective resource is being
* deleted.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack not initialized
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCStop();
* Called in main loop of OC client or server. Allows low-level processing of
* stack services.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCProcess();
* Discover or Perform requests on a specified resource (specified by that Resource's respective
* URI).
*
- * @param handle - @ref OCDoHandle 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 - @ref OCMethod to perform on the resource
- * @param requiredUri - URI of the resource to interact with
- * @param referenceUri - URI of the reference resource
- * @param request - JSON encoded request
- * @param conType - @ref OCConnectivityType type of connectivity indicating the
- * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
- * @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 complete
- * @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
+ * @param handle @ref OCDoHandle 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 @ref OCMethod to perform on the resource.
+ * @param requiredUri URI of the resource to interact with.
+ * @param referenceUri URI of the reference resource.
+ * @param request JSON encoded request.
+ * @param conType @ref OCConnectivityType type of connectivity indicating the
+ * interface. Example: ::OC_WIFI, ::OC_ETHERNET, ::OC_ALL.
+ * @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 complete.
+ * @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 (ie. 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 - no errors
- * OC_STACK_INVALID_CALLBACK - invalid callback function pointer
- * OC_STACK_INVALID_METHOD - invalid resource method
- * OC_STACK_INVALID_URI - invalid required or reference URI
- * OC_STACK_INVALID_QUERY - number of resource types specified for filtering presence
- * notifications exceeds @ref MAX_PRESENCE_FILTERS.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
const char *referenceUri, const char *request, OCConnectivityType conType,
* explicit observe cancellation
* @param numOptions- Number of header options to be included
*
- * @return
- * OC_STACK_OK - No errors; Success
- * OC_STACK_INVALID_PARAM - The handle provided is invalid.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
uint8_t numOptions);
* Server can call this function when it comes online for the first time, or when it comes back
* online from offline mode, or when it re enters network.
*
- * @param ttl - Time To Live in seconds
+ * @param ttl Time To Live in seconds.
* Note: If ttl is '0', then the default stack value will be used (60 Seconds).
*
- * @return
- * OC_STACK_OK - No errors; Success
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCStartPresence(const uint32_t ttl);
* Server can call this function when it is terminating, going offline, or when going
* away from network.
*
- * @return
- * OC_STACK_OK - No errors; Success
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCStopPresence();
/**
- * Set default device entity handler
+ * Set default device entity handler.
*
- * @param entityHandler - entity handler function that is called by ocstack to handle requests for
- * any undefined resources or default actions.
- * if NULL is passed it removes the device default entity handler.
+ * @param entityHandler Entity handler function that is called by ocstack to handle requests for
+ * any undefined resources or default actions.
+ * If NULL is passed it removes the device default entity handler.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
/**
* Set device information.
*
- * @param deviceInfo - Structure passed by the server application containing
- * the device information.
+ * @param deviceInfo Structure passed by the server application containing
+ * the device information.
*
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_INVALID_PARAM - invalid paramerter
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
/**
* Create a resource.
*
- * @param handle - pointer to handle to newly created resource. Set by ocstack. Used to refer to resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
- * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
- * @param uri - URI of the resource. Example: "/a/led"
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * NULL for default entity handler
- * @param resourceProperties - properties supported by resource. Example: OC_DISCOVERABLE|OC_OBSERVABLE
+ * @param handle Pointer to handle to newly created resource. Set by ocstack and
+ * used to refer to resource.
+ * @param resourceTypeName Name of resource type. Example: "core.led".
+ * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
+ * @param uri URI of the resource. Example: "/a/led".
+ * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
+ * NULL for default entity handler.
+ * @param resourceProperties Properties supported by resource.
+ * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCCreateResource(OCResourceHandle *handle,
const char *resourceTypeName,
uint8_t resourceProperties);
/**
- * Create a resource. with host ip address for remote resource
+ * Create a resource. with host ip address for remote resource.
*
- * @param handle - pointer to handle to newly created resource. Set by ocstack.
- * Used to refer to resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
- * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
- * @param host - HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx"
- * @param uri - URI of the resource. Example: "/a/led"
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * NULL for default entity handler
- * @param resourceProperties - properties supported by resource.
- * Example: OC_DISCOVERABLE|OC_OBSERVABLE
+ * @param handle Pointer to handle to newly created resource. Set by ocstack.
+ * Used to refer to resource.
+ * @param resourceTypeName Name of resource type. Example: "core.led".
+ * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
+ * @param host HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx".
+ * @param uri URI of the resource. Example: "/a/led".
+ * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
+ * NULL for default entity handler.
+ * @param resourceProperties Properties supported by resource.
+ * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
const char *resourceTypeName,
/**
* Add a resource to a collection resource.
*
- * @param collectionHandle - handle to the collection resource
- * @param resourceHandle - handle to resource to be added to the collection resource
+ * @param collectionHandle Handle to the collection resource.
+ * @param resourceHandle Handle to resource to be added to the collection resource.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- * OC_STACK_INVALID_PARAM - invalid collectionhandle
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
/**
* Remove a resource from a collection resource.
*
- * @param collectionHandle - handle to the collection resource
- * @param resourceHandle - handle to resource to be removed from the collection resource
+ * @param collectionHandle Handle to the collection resource.
+ * @param resourceHandle Handle to resource to be removed from the collection resource.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- * OC_STACK_INVALID_PARAM - invalid collectionhandle
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
/**
* Bind a resourcetype to a resource.
*
- * @param handle - handle to the resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
+ * @param handle Handle to the resource.
+ * @param resourceTypeName Name of resource type. Example: "core.led".
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
const char *resourceTypeName);
/**
* Bind a resource interface to a resource.
*
- * @param handle - handle to the resource
- * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
+ * @param handle Handle to the resource.
+ * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
const char *resourceInterfaceName);
/**
* Bind an entity handler to the resource.
*
- * @param handle - handle to the resource that the contained resource is to be bound
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @param handle Handle to the resource that the contained resource is to be bound.
+ * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
/**
* Get the number of resources that have been created in the stack.
*
- * @param numResources - pointer to count variable
+ * @param numResources Pointer to count variable.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
-
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCGetNumberOfResources(uint8_t *numResources);
/**
* Get a resource handle by index.
*
- * @param index - index of resource, 0 to Count - 1
+ * @param index Index of resource, 0 to Count - 1.
*
- * @return
- * Resource handle - if found
- * NULL - if not found
+ * @return Found resource handle or NULL if not found.
*/
OCResourceHandle OCGetResourceHandle(uint8_t index);
* Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
* client observers that "this" resource is being deleted.
*
- * @param handle - handle of resource to be deleted
+ * @param handle Handle of resource to be deleted.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCDeleteResource(OCResourceHandle handle);
/**
* Get the URI of the resource specified by handle.
*
- * @param handle - handle of resource
- * @return
- * URI string - if resource found
- * NULL - resource not found
+ * @param handle Handle of resource.
+ * @return URI string if resource found or NULL if not found.
*/
const char *OCGetResourceUri(OCResourceHandle handle);
* NOTE: that after a resource is created, the OC_ACTIVE property is set
* for the resource by the stack.
*
- * @param handle - handle of resource
- * @return
- * OCResourceProperty Bitmask
- * -1 if resource is not found
+ * @param handle Handle of resource.
+ * @return OCResourceProperty Bitmask or -1 if resource is not found.
*/
OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
/**
* Get the number of resource types of the resource.
*
- * @param handle - handle of resource
- * @param numResourceTypes - pointer to count variable
+ * @param handle Handle of resource.
+ * @param numResourceTypes Pointer to count variable.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
/**
* Get name of resource type of the resource.
*
- * @param handle - handle of resource
- * @param index - index of resource, 0 to Count - 1
+ * @param handle Handle of resource.
+ * @param index Index of resource, 0 to Count - 1.
*
- * @return
- * resource type name - if resource found
- * NULL - resource not found
+ * @return Resource type name if resource found or NULL if resource not found.
*/
const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
/**
* Get the number of resource interfaces of the resource.
*
- * @param handle - handle of resource
- * @param numResourceInterfaces - pointer to count variable
+ * @param handle Handle of resource.
+ * @param numResourceInterfaces Pointer to count variable.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
-
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
uint8_t *numResourceInterfaces);
/**
* Get name of resource interface of the resource.
*
- * @param handle - handle of resource
- * @param index - index of resource, 0 to Count - 1
+ * @param handle Handle of resource.
+ * @param index Index of resource, 0 to Count - 1.
*
- * @return
- * resource interface name - if resource found
- * NULL - resource not found
+ * @return Resource interface name if resource found or NULL if resource not found.
*/
const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
/**
* Get methods of resource interface of the resource.
*
- * @param handle - handle of resource
- * @param index - index of resource, 0 to Count - 1
+ * @param handle Handle of resource.
+ * @param index Index of resource, 0 to Count - 1.
*
- * @return
- * allowed methods - if resource found
- * NULL - resource not found
+ * @return Allowed methods if resource found or NULL if resource not found.
*/
uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
/**
* Get resource handle from the collection resource by index.
*
- * @param collectionHandle - handle of collection resource
- * @param index - index of contained resource, 0 to Count - 1
+ * @param collectionHandle Handle of collection resource.
+ * @param index Index of contained resource, 0 to Count - 1.
*
- * @return
- * handle to contained resource - if resource found
- * NULL - resource not found
+ * @return Handle to contained resource if resource found or NULL if resource not found.
*/
OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
uint8_t index);
/**
* Get the entity handler for a resource.
*
- * @param handle - handle of resource
+ * @param handle Handle of resource.
*
- * @return
- * entity handler - if resource found
- * NULL - resource not found
+ * @return Entity handler if resource found or NULL resource not found.
*/
OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
* changed. If observation includes a query the client is notified only
* if the query is valid after the resource representation has changed.
*
- * @param handle - handle of resource
- * @param qos - desired quality of service for the observation notifications
+ * @param handle Handle of resource.
+ * @param qos Desired quality of service for the observation notifications.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_NO_RESOURCE - invalid resource handle
- * OC_STACK_NO_OBSERVERS - no more observers intrested in resource
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
* Before this API is invoked by entity handler it has finished processing
* queries for the associated observers.
*
- * @param handle - handle of resource
- * @param obsIdList - list of observation ids that need to be notified
- * @param numberOfIds - number of observation ids included in obsIdList
- * @param notificationJSONPayload - JSON encoded payload to send in notification
- * @param qos - desired quality of service of the observation notifications
+ * @param handle Handle of resource.
+ * @param obsIdList List of observation ids that need to be notified.
+ * @param numberOfIds Number of observation ids included in obsIdList.
+ * @param notificationJSONPayload JSON encoded payload to send in notification.
+ * @param qos Desired quality of service of the observation notifications.
* NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
* entity invoking the API. The maximum size of the notification is 1015 bytes
* for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
*
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_NO_RESOURCE - invalid resource handle
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult
OCNotifyListOfObservers (OCResourceHandle handle,
/**
* Send a response to a request.
* The response can be a normal, slow, or block (i.e. a response that
- * is too large to be sent in a single PDU and must span multiple transmissions)
+ * is too large to be sent in a single PDU and must span multiple transmissions).
*
- * @param response - pointer to structure that contains response parameters
+ * @param response Pointer to structure that contains response parameters.
*
- * @return
- * OC_STACK_OK - no errors
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
/**
- * Cancel a response. Applies to a block response
+ * Cancel a response. Applies to a block response.
*
- * @param responseHandle - response handle set by stack in OCServerResponse after
- * OCDoResponse is called
+ * @param responseHandle Response handle set by stack in OCServerResponse after
+ * OCDoResponse is called.
*
- * @return
- * OC_STACK_OK - No errors; Success
- * OC_STACK_INVALID_PARAM - The handle provided is invalid.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult OCCancelResponse(OCResponseHandle responseHandle);
//Utility methods
-//-- OCDevAddrToIPv4Addr -------------------------------------------------
/**
* This method is used to retrieved the IPv4 address from OCDev address
* data structure.
*
- * @param[in] ipAddr
- * OCDevAddr address.
- * @param[out] a first byte of IPv4 address.
- * @param[out] b second byte of IPv4 address.
- * @param[out] c third byte of IPv4 address.
- * @param[out] d fourth byte of IPv4 address.
- *
- * @retval 0 for Success, otherwise some error value
+ * @param ipAddr OCDevAddr address.
+ * @param a first byte of IPv4 address.
+ * @param b second byte of IPv4 address.
+ * @param c third byte of IPv4 address.
+ * @param d fourth byte of IPv4 address.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
-//------------------------------------------------------------------------
int32_t OCDevAddrToIPv4Addr(OCDevAddr *ipAddr, uint8_t *a, uint8_t *b,
uint8_t *c, uint8_t *d );
-
-//-- OCDevAddrToPort -------------------------------------------------
/**
* This method is used to retrieve the port number from OCDev address
* data structure.
*
- * @param[in] ipAddr
- * OCDevAddr address.
- * @param[out] port
- * port number
- *
- * @retval 0 for Success, otherwise some error value
+ * @param ipAddr OCDevAddr address.
+ * @param port Port number.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
*/
-//------------------------------------------------------------------------
int32_t OCDevAddrToPort(OCDevAddr *ipAddr, uint16_t *port);
#ifdef __cplusplus
static struct ResourceObserver * serverObsList = NULL;
-// send notifications based on the qos of the request
-// The qos passed as a parameter overrides what the client requested
-// If we want the client preference taking high priority make:
-// qos = resourceObserver->qos;
-OCQualityOfService DetermineObserverQoS(OCMethod method, ResourceObserver * resourceObserver,
- OCQualityOfService appQoS)
+/**
+ * Determine observe QOS based on the QOS of the request.
+ * The qos passed as a parameter overrides what the client requested.
+ * If we want the client preference taking high priority make:
+ * qos = resourceObserver->qos;
+ *
+ * @param method RESTful method.
+ * @param resourceObserver Observer.
+ * @param appQoS Quality of service.
+ * @return The quality of service of the observer.
+ */
+static OCQualityOfService DetermineObserverQoS(OCMethod method,
+ ResourceObserver * resourceObserver, OCQualityOfService appQoS)
{
if(!resourceObserver)
{
OCServerRequest * request = NULL;
OCEntityHandlerRequest ehRequest = {};
OCEntityHandlerResult ehResult = OC_EH_ERROR;
+ bool observeErrorFlag = false;
// Find clients that are observing this resource
while (resourceObserver)
}
}
#endif
+
+ // Since we are in a loop, set an error flag to indicate at least one error occurred.
+ if (result != OC_STACK_OK)
+ {
+ observeErrorFlag = true;
+ }
}
resourceObserver = resourceObserver->next;
}
+
if (numObs == 0)
{
OC_LOG(INFO, TAG, PCF("Resource has no observers"));
result = OC_STACK_NO_OBSERVERS;
}
+ else if (observeErrorFlag)
+ {
+ OC_LOG(ERROR, TAG, PCF("Observer notification error"));
+ result = OC_STACK_ERROR;
+ }
return result;
}
uint8_t numSentNotification = 0;
OCServerRequest * request = NULL;
OCStackResult result = OC_STACK_ERROR;
+ bool observeErrorFlag = false;
OC_LOG(INFO, TAG, PCF("Entering SendListObserverNotification"));
while(numIds)
result = OCDoResponse(&ehResponse);
if(result == OC_STACK_OK)
{
+ // Increment sent notifications only if OCDoResponse is successful
+ numSentNotification++;
+
OCFree(ehResponse.payload);
FindAndDeleteServerRequest(request);
}
FindAndDeleteServerRequest(request);
}
}
-
- numSentNotification++;
+ // Since we are in a loop, set an error flag to indicate
+ // at least one error occurred.
+ if (result != OC_STACK_OK)
+ {
+ observeErrorFlag = true;
+ }
}
}
obsIdList++;
numIds--;
}
- if(numSentNotification == numberOfIds)
+
+ if(numSentNotification == numberOfIds && !observeErrorFlag)
{
return OC_STACK_OK;
}
}
else
{
- //TODO: we need to signal that not every one in the
- // list got an update, should we also indicate who did not receive on?
- return OC_STACK_OK;
+ OC_LOG(ERROR, TAG, PCF("Observer notification error"));
+ return OC_STACK_ERROR;
}
}
//TODO: we should allow the server to define this
#define MAX_OBSERVE_AGE (0x2FFFFUL)
+/**
+ * Parse the presence payload and extract various parameters.
+ * Note: Caller should invoke OCFree after done with resType pointer.
+ *
+ * @param payload Presence payload.
+ * @param seqNum Sequence number.
+ * @param maxAge Time To Live (in seconds).
+ * @param resType Resource type.
+ */
// TODO: Not sure if I agree with this. I think it should be static but it is called in
// stack/test/stacktests.cpp, not included via a header file. If we intend to allow it
// to be called externally, we should change the name to OCParsePresencePayload and make
// it part of the official public API. But can't change now due to current API freeze.
-// Another option might be to make non-API utility functions for doing stuff like this
+// Another option might be to make non-API utility functions for doing stuff like this.
void parsePresencePayload(char* payload, uint32_t* seqNum, uint32_t* maxAge, char** resType);
//-----------------------------------------------------------------------------
// Private internal function prototypes
//-----------------------------------------------------------------------------
+
+/**
+ * Generate handle of OCDoResource invocation for callback management.
+ *
+ * @return Generated OCDoResource handle.
+ */
static OCDoHandle GenerateInvocationHandle();
+
+/**
+ * Initialize resource data structures, variables, etc.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult initResources();
+
+/**
+ * Add a resource to the end of the linked list of resources.
+ *
+ * @param resource Resource to be added
+ */
static void insertResource(OCResource *resource);
+
+/**
+ * Find a resource in the linked list of resources.
+ *
+ * @param resource Resource to be found.
+ * @return Pointer to resource that was found in the linked list or NULL if the resource was not
+ * found.
+ */
static OCResource *findResource(OCResource *resource);
+
+/**
+ * Insert a resource type into a resource's resource type linked list.
+ * If resource type already exists, it will not be inserted and the
+ * resourceType will be free'd.
+ * resourceType->next should be null to avoid memory leaks.
+ * Function returns silently for null args.
+ *
+ * @param resource Resource where resource type is to be inserted.
+ * @param resourceType Resource type to be inserted.
+ */
static void insertResourceType(OCResource *resource,
OCResourceType *resourceType);
+
+/**
+ * Get a resource type at the specified index within a resource.
+ *
+ * @param handle Handle of resource.
+ * @param index Index of resource type.
+ *
+ * @return Pointer to resource type if found, NULL otherwise.
+ */
static OCResourceType *findResourceTypeAtIndex(OCResourceHandle handle,
uint8_t index);
+
+/**
+ * Insert a resource interface into a resource's resource interface linked list.
+ * If resource interface already exists, it will not be inserted and the
+ * resourceInterface will be free'd.
+ * resourceInterface->next should be null to avoid memory leaks.
+ *
+ * @param resource Resource where resource interface is to be inserted.
+ * @param resourceInterface Resource interface to be inserted.
+ */
static void insertResourceInterface(OCResource *resource,
OCResourceInterface *resourceInterface);
+
+/**
+ * Get a resource interface at the specified index within a resource.
+ *
+ * @param handle Handle of resource.
+ * @param index Index of resource interface.
+ *
+ * @return Pointer to resource interface if found, NULL otherwise.
+ */
static OCResourceInterface *findResourceInterfaceAtIndex(
OCResourceHandle handle, uint8_t index);
+
+/**
+ * Delete all of the dynamically allocated elements that were created for the resource type.
+ *
+ * @param resourceType Specified resource type.
+ */
static void deleteResourceType(OCResourceType *resourceType);
+
+/**
+ * Delete all of the dynamically allocated elements that were created for the resource interface.
+ *
+ * @param resourceInterface Specified resource interface.
+ */
static void deleteResourceInterface(OCResourceInterface *resourceInterface);
+
+/**
+ * Delete all of the dynamically allocated elements that were created for the resource.
+ *
+ * @param resource Specified resource.
+ */
static void deleteResourceElements(OCResource *resource);
+
+/**
+ * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
+ * linked lists.
+ *
+ * @param handle Handle of resource to be deleted.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult deleteResource(OCResource *resource);
+
+/**
+ * Delete all of the resources in the resource list.
+ */
static void deleteAllResources();
+
+/**
+ * Increment resource sequence number. Handles rollover.
+ *
+ * @param resPtr Pointer to resource.
+ */
static void incrementSequenceNumber(OCResource * resPtr);
+
+/**
+ * Verify the lengths of the URI and the query separately.
+ *
+ * @param inputUri Input URI and query.
+ * @param uriLen The length of the initial URI with query.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult verifyUriQueryLength(const char * inputUri,
uint16_t uriLen);
+
+/**
+ * Determine if a request/response must be sent in a block transfer because it is too large to be
+ * sent in a single PDU. This function can be used for either a request or a response.
+ * Note: Either the request or response parameter should be non-NULL (i.e. only one, not both).
+ *
+ * @param request NULL or pointer to request.
+ * @param response NULL or pointer to response.
+ * @param size 0 or size of the request/response. If 0, strlen is used for determining
+ * the length of the request/response.
+ *
+ * @return
+ * false - packet transfer NOT required (i.e. normal request/response).
+ * true - packet transfer required (i.e. block transfer needed).
+ */
static bool OCIsPacketTransferRequired(const char *request, const char *response, size_t size);
+
+/**
+ * Retrieves a resource type based upon a query contains only just one
+ * resource attribute (and that has to be of type "rt").
+ *
+ * @remark This API malloc's memory for the resource type. Do not malloc resourceType
+ * before passing in.
+ *
+ * @param query The query part of the URI.
+ * @param resourceType The resource type to be populated; pass by reference.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult getResourceType(const char * query, char** resourceType);
+
+/*
+ * Attempts to initialize every network interface that the CA Layer might have compiled in.
+ *
+ * Note: At least one interface must succeed to initialize. If all calls to @ref CASelectNetwork
+ * return something other than @ref CA_STATUS_OK, then this function fails.
+ *
+ * @return ::CA_STATUS_OK on success, some other value upon failure.
+ */
static CAResult_t OCSelectNetwork();
+
+/**
+ * Get the CoAP ticks after the specified number of seconds.
+ *
+ * @param afterSeconds Seconds.
+ * @return
+ * CoAP ticks
+ */
static uint32_t GetTime(float afterSeconds);
+
+/**
+ * This method is used to create the IPv4 dev_addr structure.
+ * Builds a socket interface address using IP address and port number.
+ * TODO: Remove in future. Temporary helper function.
+ *
+ * @param a IPv4 octet 0.
+ * @param b IPv4 octet 1.
+ * @param c IPv4 octet 2.
+ * @param d IPv4 octet 3.
+ * @param port Port number.
+ * @param ipAddr - IPv4 address.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult OCBuildIPv4Address(uint8_t a, uint8_t b, uint8_t c, uint8_t d,
uint16_t port, OCDevAddr *ipAddr);
+
+/**
+ * Convert CAResponseResult_t to OCStackResult.
+ *
+ * @param caCode CAResponseResult_t code.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult CAToOCStackResult(CAResponseResult_t caCode);
+
+/**
+ * Convert OCConnectivityType to CAConnectivityType_t.
+ *
+ * @param ocConType OCConnectivityType input.
+ * @param caConType CAConnectivityType_t output.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult OCToCAConnectivityType(OCConnectivityType ocConType,
CAConnectivityType_t* caConType);
+
+/**
+ * Convert CAConnectivityType_t to CAConnectivityType_t.
+ *
+ * @param caConType CAConnectivityType_t input.
+ * @param ocConType OCConnectivityType output.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult CAToOCConnectivityType(CAConnectivityType_t caConType,
OCConnectivityType *ocConType);
+
+/**
+ * Update response.addr appropriately from endPoint.addressInfo.
+ *
+ * @param address OCDevAddr output.
+ * @param endPoint CARemoteEndpoint_t input.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult UpdateResponseAddr(OCDevAddr *address, const CARemoteEndpoint_t* endPoint);
+
+/**
+ * Handle response from presence request.
+ *
+ * @param endPoint CA remote endpoint.
+ * @param responseInfo CA response info.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult HandlePresenceResponse(const CARemoteEndpoint_t* endPoint,
const CAResponseInfo_t* responseInfo);
+
+/**
+ * This function will be called back by CA layer when a response is received.
+ *
+ * @param endPoint CA remote endpoint.
+ * @param responseInfo CA response info.
+ */
static void HandleCAResponses(const CARemoteEndpoint_t* endPoint,
const CAResponseInfo_t* responseInfo);
+
+/**
+ * This function will be called back by CA layer when a request is received.
+ *
+ * @param endPoint CA remote endpoint.
+ * @param requestInfo CA request info.
+ */
static void HandleCARequests(const CARemoteEndpoint_t* endPoint,
const CARequestInfo_t* requestInfo);
+
+/**
+ * Handle incoming requests.
+ *
+ * @param protocolRequest Incoming request from lower level stack.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult HandleStackRequests(OCServerProtocolRequest * protocolRequest);
+
+/**
+ * Parse IP address string into octets and port.
+ *
+ * @param ipAddrStr IPv4 address input string.
+ * @param ipAddr IPv4 address output.
+ * @param port Port number.
+ * @return
+ * true - success.
+ * false - failure.
+ */
static bool ParseIPv4Address(char * ipAddrStr, uint8_t * ipAddr, uint16_t * port);
+
+/**
+ * Extract query from a URI.
+ *
+ * @param uri Full URI with query.
+ * @param query Pointer to string that will contain query.
+ * @param newURI Pointer to string that will contain URI.
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
static OCStackResult getQueryFromUri(const char * uri, char** resourceType, char ** newURI);
-//-----------------------------------------------------------------------------
-// Internal functions
-//-----------------------------------------------------------------------------
+/**
+ * Finds a resource type in an OCResourceType link-list.
+ *
+ * @param resourceTypeList The link-list to be searched through.
+ * @param resourceTypeName The key to search for.
+ *
+ * @return Resource type that matches the key (ie. resourceTypeName) or
+ * NULL if there is either an invalid parameter or this function was unable to find the key.
+ */
+static OCResourceType *findResourceType(OCResourceType * resourceTypeList,
+ const char * resourceTypeName);
/**
- * Get the CoAP ticks after the specified number of seconds
+ * Return a server instance ID.
*
- * @param afterSeconds - seconds
- * @return
- * CoAP ticks
+ * @return Instance ID of the server.
*/
+static const ServerID OCGetServerInstanceID(void);
+
+//-----------------------------------------------------------------------------
+// Internal functions
+//-----------------------------------------------------------------------------
+
uint32_t GetTime(float afterSeconds)
{
coap_tick_t now;
return now + (uint32_t)(afterSeconds * COAP_TICKS_PER_SECOND);
}
-/**
- * This method is used to create the IPv4 dev_addr structure.
- * Builds a socket interface address using IP address and port number
- * TODO: Remove in future. Temporary helper function.
- *
- * @param a - IPv4 octet 0
- * @param b - IPv4 octet 1
- * @param c - IPv4 octet 2
- * @param d - IPv4 octet 3
- * @param port - port number
- * @param ipAddr - IPv4 address
- * @return
- * OCStackResult
- */
-
OCStackResult OCBuildIPv4Address(uint8_t a, uint8_t b, uint8_t c, uint8_t d,
uint16_t port, OCDevAddr *ipAddr)
{
return OC_STACK_OK;
}
-
-/**
- * Convert CAResponseResult_t to OCStackResult
- * @param caCode - CAResponseResult_t code
- * @return
- * OCStackResult
- */
OCStackResult CAToOCStackResult(CAResponseResult_t caCode)
{
OCStackResult ret = OC_STACK_ERROR;
return ret;
}
-/**
- * Convert OCConnectivityType to CAConnectivityType_t
- * @param ocConType - OCConnectivityType input
- * @param caConType - CAConnectivityType_t output
- * @return
- * OCStackResult
- */
OCStackResult OCToCAConnectivityType(OCConnectivityType ocConType, CAConnectivityType_t* caConType)
{
OCStackResult ret = OC_STACK_OK;
}
return ret;
}
-/**
- * Convert CAConnectivityType_t to CAConnectivityType_t
- * @param caConType - CAConnectivityType_t input
- * @param ocConType - OCConnectivityType output
- * @return
- * OCStackResult
- */
+
OCStackResult CAToOCConnectivityType(CAConnectivityType_t caConType, OCConnectivityType *ocConType)
{
OCStackResult ret = OC_STACK_OK;
return ret;
}
-/**
- * Update response.addr appropriately from endPoint.addressInfo
- * @param address - OCDevAddr output
- * @param endPoint - CARemoteEndpoint_t input
- * @return
- * OCStackResult
- */
OCStackResult UpdateResponseAddr(OCDevAddr *address, const CARemoteEndpoint_t* endPoint)
{
OCStackResult ret = OC_STACK_ERROR;
OCFree(cpAddress);
return ret;
}
-/**
- * Parse the presence payload and extract various parameters
- * Note: Caller should invoke OCFree after done with resType pointer
- * @param payload - presence payload
- * @param seqNum - sequence number
- * @param maxAge - max age
- * @param resType - resource type
- */
+
void parsePresencePayload(char* payload, uint32_t* seqNum, uint32_t* maxAge, char** resType)
{
char * tok = NULL;
payload[strlen((char *)payload)] = ']';
}
-/**
- * Handle response from presence request
- * @param endPoint - CA remote endpoint
- * @param responseInfo - CA response info
- * @return
- * OCStackResult
- */
static OCStackResult HandlePresenceResponse(const CARemoteEndpoint_t* endPoint,
const CAResponseInfo_t* responseInfo)
{
return result;
}
-/**
- * This function will be called back by CA layer when a response is received
- * @param endPoint
- * @param responseInfo
- */
void HandleCAResponses(const CARemoteEndpoint_t* endPoint, const CAResponseInfo_t* responseInfo)
{
OC_LOG(INFO, TAG, PCF("Enter HandleCAResponses"));
OC_LOG(INFO, TAG, PCF("Exit HandleCAResponses"));
}
-/**
- * This function will be called back by CA layer when a request is received
- * @param endPoint
- * @param requestInfo
- */
void HandleCARequests(const CARemoteEndpoint_t* endPoint, const CARequestInfo_t* requestInfo)
{
OC_LOG(INFO, TAG, PCF("Enter HandleCARequests"));
OC_LOG(INFO, TAG, PCF("Exit HandleCARequests"));
}
-/**
- * Handle incoming requests
- * @param protocolRequest
- * @return
- * OCStackResult
- */
OCStackResult HandleStackRequests(OCServerProtocolRequest * protocolRequest)
{
OC_LOG(INFO, TAG, PCF("Entering HandleStackRequests (OCStack Layer)"));
return result;
}
-/**
- * Parse IP address string into octets and port
- * @param ipAddrStr
- * @param ipAddr
- * @param port
- * @return
- * true - success
- * false - failure
- */
bool ParseIPv4Address(char * ipAddrStr, uint8_t * ipAddr, uint16_t * port)
{
size_t index = 0;
// Public APIs
//-----------------------------------------------------------------------------
-/**
- * Initialize the OC Stack. Must be called prior to starting the stack.
- *
- * @param ipAddr
- * IP Address of host device
- * @param port
- * Port of host device
- * @param mode
- * Host device is client, server, or client-server
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack init error
- */
OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode)
{
(void) ipAddr;
return result;
}
-/**
- * Stop the OC stack. Use for a controlled shutdown.
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack not initialized
- */
OCStackResult OCStop()
{
OC_LOG(INFO, TAG, PCF("Entering OCStop"));
return OC_STACK_OK;
}
-/**
- * Map OCQualityOfService to CAMessageType
- *
- * @param OCQualityOfService - Input qos.
- *
- * Returns CA message type for a given qos.
- */
CAMessageType_t qualityOfServiceToMessageType(OCQualityOfService qos)
{
switch (qos)
}
}
-/**
- * Verify the lengths of the URI and the query separately
- *
- * @param inputUri - Input URI and query.
- * @param uriLen - The length of the initial URI with query.
- *
- * Note: The '?' that appears after the URI is not considered as
- * a part of the query.
- */
OCStackResult verifyUriQueryLength(const char *inputUri, uint16_t uriLen)
{
char *query;
return OC_STACK_OK;
}
-/**
- * Discover or Perform requests on a specified resource
- * (specified by that Resource's respective URI).
- *
- * @param handle - @ref OCDoHandle to refer to the request sent out on behalf of
- * calling this API.
- * @param method - @ref OCMethod to perform on the resource
- * @param requiredUri - URI of the resource to interact with
- * @param referenceUri - URI of the reference resource
- * @param request - JSON encoded request
- * @param qos - quality of service
- * @param cbData - struct that contains asynchronous callback function that is invoked
- * by the stack when discovery or resource interaction is complete
- * @param options - The address of an array containing the vendor specific header
- * header options to be sent with the request
- * @param numOptions - Number of vendor specific header options to be included
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_INVALID_CALLBACK - invalid callback function pointer
- * OC_STACK_INVALID_METHOD - invalid resource method
- * OC_STACK_INVALID_URI - invalid required or reference URI
- *
- * Note: when using multicast, the required URI should not contain IP address.
- * Instead, it just contains the URI to the resource such as "/oc/core".
- */
OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
const char *referenceUri, const char *request, OCConnectivityType conType,
OCQualityOfService qos, OCCallbackData *cbData,
return result;
}
-/**
- * Cancel a request associated with a specific @ref OCDoResource invocation.
- *
- * @param handle - Used to identify a specific OCDoResource invocation.
- * @param qos - used to specify Quality of Service (read below for more info)
- * @param options- used to specify vendor specific header options when sending
- * explicit observe cancellation
- * @param numOptions- Number of header options to be included
- *
- * @return
- * OC_STACK_OK - No errors; Success
- * OC_STACK_INVALID_PARAM - The handle provided is invalid.
- */
OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
uint8_t numOptions)
{
return ret;
}
-/**
- * Perform presence notifications
- *
- * @return
- * OCStackResult
- */
#ifdef WITH_PRESENCE
OCStackResult OCProcessPresence()
{
}
#endif // WITH_PRESENCE
-/**
- * Called in main loop of OC client or server. Allows low-level processing of
- * stack services.
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCProcess()
{
#ifdef WITH_PRESENCE
}
#ifdef WITH_PRESENCE
-/**
- * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
- * presence notifications to clients via multicast. Once this API has been called with a success,
- * clients may query for this server's presence and this server's stack will respond via multicast.
- *
- * Server can call this function when it comes online for the first time, or when it comes back
- * online from offline mode, or when it re enters network.
- *
- * @param ttl - Time To Live in seconds
- * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
- *
- * @return
- * OC_STACK_OK - No errors; Success
- */
OCStackResult OCStartPresence(const uint32_t ttl)
{
uint8_t tokenLength = CA_MAX_TOKEN_LEN;
return SendPresenceNotification(NULL);
}
-/**
- * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
- * presence notifications to clients via multicast. Once this API has been called with a success,
- * this server's stack will not respond to clients querying for this server's presence.
- *
- * Server can call this function when it is terminating, going offline, or when going
- * away from network.
- *
- * @return
- * OC_STACK_OK - No errors; Success
- */
OCStackResult OCStopPresence()
{
OCStackResult result = OC_STACK_ERROR;
}
#endif
-/**
- * Set default device entity handler
- *
- * @param entityHandler - entity handler function that is called by ocstack to handle requests for
- * any undefined resources or default actions.
- * if NULL is passed it removes the device default entity handler.
- *
- * @return
- * OC_STACK_OK - no errors
- */
OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler)
{
defaultDeviceHandler = entityHandler;
return OC_STACK_OK;
}
-/**
- * Set device information.
- *
- * @param deviceInfo - Structure passed by the server application containing
- * the device information.
- *
- *
- * @return
- * OCStackResult
- */
OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo)
{
OC_LOG(INFO, TAG, PCF("Entering OCSetDeviceInfo"));
}
}
-/**
- * Create a resource
- *
- * @param handle - pointer to handle to newly created resource. Set by ocstack.
- * Used to refer to resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
- * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
- * @param uri - URI of the resource. Example: "/a/led"
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * NULL for default entity handler
- * @param resourceProperties - properties supported by resource.
- * Example: OC_DISCOVERABLE|OC_OBSERVABLE
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCCreateResource(OCResourceHandle *handle,
const char *resourceTypeName,
const char *resourceInterfaceName,
return result;
}
-
-
-/**
- * Create a resource. with host ip address for remote resource
- *
- * @param handle - pointer to handle to newly created resource. Set by ocstack.
- * Used to refer to resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
- * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
- * @param host - HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx"
- * @param uri - URI of the resource. Example: "/a/led"
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * NULL for default entity handler
- * @param resourceProperties - properties supported by resource.
- * Example: OC_DISCOVERABLE|OC_OBSERVABLE
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
-
OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
const char *resourceTypeName,
const char *resourceInterfaceName,
return result;
}
-/**
- * Add a resource to a collection resource.
- *
- * @param collectionHandle - handle to the collection resource
- * @param resourceHandle - handle to resource to be added to the collection resource
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- * OC_STACK_INVALID_PARAM - invalid collectionhandle
- */
OCStackResult OCBindResource(
OCResourceHandle collectionHandle, OCResourceHandle resourceHandle)
{
return OC_STACK_ERROR;
}
-/**
- * Remove a resource from a collection resource.
- *
- * @param collectionHandle - handle to the collection resource
- * @param resourceHandle - handle to resource to be added to the collection resource
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- * OC_STACK_INVALID_PARAM - invalid collectionHandle
- */
OCStackResult OCUnBindResource(
OCResourceHandle collectionHandle, OCResourceHandle resourceHandle)
{
return OC_STACK_ERROR;
}
-/**
- * Bind a resourcetype to a resource
- *
- * @param resource - target resource
- * @param resourceTypeName - resourcetype
- * @return
- * OCStackResult
- */
OCStackResult BindResourceTypeToResource(OCResource* resource,
const char *resourceTypeName)
{
return result;
}
-/**
- * Bind a resource interface to a resource
- *
- * @param resource - target resource
- * @param resourceInterfaceName - resource interface
- * @return
- * OCStackResult
- */
OCStackResult BindResourceInterfaceToResource(OCResource* resource,
const char *resourceInterfaceName)
{
return result;
}
-/**
- * Bind a resourcetype to a resource.
- *
- * @param handle - handle to the resource
- * @param resourceTypeName - name of resource type. Example: "core.led"
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
const char *resourceTypeName)
{
return result;
}
-/**
- * Bind a resourceinterface to a resource.
- *
- * @param handle - handle to the resource
- * @param resourceInterfaceName - name of resource interface. Example: "oc.mi.b"
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
-
OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
const char *resourceInterfaceName)
{
return result;
}
-/**
- * Get the number of resources that have been created in the stack.
- *
- * @param numResources - pointer to count variable
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
-
- */
OCStackResult OCGetNumberOfResources(uint8_t *numResources)
{
OCResource *pointer = headResource;
return OC_STACK_OK;
}
-/**
- * Get a resource handle by index.
- *
- * @param index - index of resource, 0 to Count - 1
- *
- * @return
- * Resource handle - if found
- * NULL - if not found
- */
OCResourceHandle OCGetResourceHandle(uint8_t index)
{
OCResource *pointer = headResource;
return (OCResourceHandle) pointer;
}
-/**
- * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
- * linked lists.
- *
- * @param handle - handle of resource to be deleted
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- * OC_STACK_NO_RESOURCE - resource not found
- * OC_STACK_INVALID_PARAM - invalid param
- */
OCStackResult OCDeleteResource(OCResourceHandle handle)
{
OC_LOG(INFO, TAG, PCF("Entering OCDeleteResource"));
return OC_STACK_OK;
}
-/**
- * Get the URI of the resource specified by handle.
- *
- * @param handle - handle of resource
- * @return
- * URI string - if resource found
- * NULL - resource not found
- */
const char *OCGetResourceUri(OCResourceHandle handle)
{
OCResource *resource = NULL;
return (const char *) NULL;
}
-/**
- * Get the properties of the resource specified by handle.
- * NOTE: that after a resource is created, the OC_ACTIVE property is set
- * for the resource by the stack.
- *
- * @param handle - handle of resource
- * @return
- * OCResourceProperty Bitmask
- * -1 if resource is not found
- */
OCResourceProperty OCGetResourceProperties(OCResourceHandle handle)
{
OCResource *resource = NULL;
return (OCResourceProperty)-1;
}
-/**
- * Get the number of resource types of the resource.
- *
- * @param handle - handle of resource
- * @param numResourceTypes - pointer to count variable
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle,
uint8_t *numResourceTypes)
{
return OC_STACK_OK;
}
-/**
- * Get name of resource type of the resource.
- *
- * @param handle - handle of resource
- * @param index - index of resource, 0 to Count - 1
- *
- * @return
- * resource type name - if resource found
- * NULL - resource not found
- */
const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index)
{
OCResourceType *resourceType = NULL;
return (const char *) NULL;
}
-/**
- * Get the number of resource interfaces of the resource.
- *
- * @param handle - handle of resource
- * @param numResources - pointer to count variable
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
uint8_t *numResourceInterfaces)
{
return OC_STACK_OK;
}
-/**
- * Get name of resource interface of the resource.
- *
- * @param handle - handle of resource
- * @param index - index of resource, 0 to Count - 1
- *
- * @return
- * resource interface name - if resource found
- * NULL - resource not found
- */
const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index)
{
OCResourceInterface *resourceInterface = NULL;
return (const char *) NULL;
}
-/**
- * Get resource handle from the collection resource by index.
- *
- * @param collectionHandle - handle of collection resource
- * @param index - index of contained resource, 0 to Count - 1
- *
- * @return
- * handle to resource - if resource found
- * NULL - resource not found
- */
OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
uint8_t index)
{
return resource->rsrcResources[index];
}
-/**
- * Bind an entity handler to the resource.
- *
- * @param handle - handle to the resource that the contained resource is to be bound
- * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
OCStackResult OCBindResourceHandler(OCResourceHandle handle,
OCEntityHandler entityHandler)
{
return OC_STACK_OK;
}
-/**
- * Get the entity handler for a resource.
- *
- * @param handle - handle of resource
- *
- * @return
- * entity handler - if resource found
- * NULL - resource not found
- */
OCEntityHandler OCGetResourceHandler(OCResourceHandle handle)
{
OCResource *resource = NULL;
return resource->entityHandler;
}
-/**
- * Increment resource sequence number. Handles rollover
- *
- * @param resPtr - pointer to resource
- */
void incrementSequenceNumber(OCResource * resPtr)
{
// Increment the sequence number
return;
}
-/**
- * Notify Presence subscribers that a resource has been modified
- *
- * @param resourceType - Handle to the resourceType linked list of resource
- * that was modified.
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- */
#ifdef WITH_PRESENCE
OCStackResult SendPresenceNotification(OCResourceType *resourceType)
{
return result;
}
-/**
- * Send Stop Notification to Presence subscribers
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_ERROR - stack process error
- *
- */
OCStackResult SendStopNotification()
{
OCResource *resPtr = NULL;
}
#endif // WITH_PRESENCE
-/**
- * Notify observers that an observed value has changed.
- *
- * @param handle - handle of resource
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_NO_RESOURCE - invalid resource handle
- * OC_STACK_NO_OBSERVERS - no more observers intrested in resource
- */
OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos)
{
}
}
-/**
- * Notify specific observers with updated value of representation.
- * Before this API is invoked by entity handler it has finished processing
- * queries for the associated observers.
- *
- * @param handle - handle of resource
- * @param obsIdList - list of observation ids that need to be notified
- * @param numberOfIds - number of observation ids included in obsIdList
- * @param notificationJSONPayload - JSON encoded payload to send in notification
- * @param qos - desired quality of service of the observation notifications
- * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
- * entity invoking the API. The maximum size of the notification is 1015 bytes
- * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
- *
- * @return
- * OC_STACK_OK - no errors
- * OC_STACK_NO_RESOURCE - invalid resource handle
- */
OCStackResult
OCNotifyListOfObservers (OCResourceHandle handle,
OCObservationId *obsIdList,
notificationJSONPayload, maxAge, qos));
}
-/**
- * Send a response to a request.
- * The response can be a regular, slow, or block (i.e. a response that
- * is too large to be sent in a single PDU and must span multiple transmissions)
- *
- * @param response - pointer to structure that contains response parameters
- *
- * @return
- * OC_STACK_OK - No errors; Success
- * OC_STACK_INVALID_PARAM - Invalid pointer to OCServerResponse
- * OC_STACK_INVALID_REQUEST_HANDLE - Request handle not found
- * OC_STACK_PERSISTENT_BUFFER_REQUIRED - Block transfer needed for response, so a
- * persistent response buffer is necessary
- */
OCStackResult OCDoResponse(OCEntityHandlerResponse *ehResponse)
{
OCStackResult result = OC_STACK_ERROR;
return result;
}
-/**
- * Cancel a response. Applies to a block response
- *
- * @param responseHandle - response handle set by stack in OCServerResponse after
- * OCDoResponse is called
- *
- * @return
- * OC_STACK_OK - No errors; Success
- * OC_STACK_INVALID_PARAM - The handle provided is invalid.
- */
OCStackResult OCCancelResponse(OCResponseHandle responseHandle)
{
OCStackResult result = OC_STACK_NOTIMPL;
//-----------------------------------------------------------------------------
// Private internal function definitions
//-----------------------------------------------------------------------------
-/**
- * Generate handle of OCDoResource invocation for callback management.
- *
- * @return
- * OCDoHandle
- */
static OCDoHandle GenerateInvocationHandle()
{
OCDoHandle handle = NULL;
return handle;
}
-/**
- * Enable/disable a resource property
- *
- * @param inputProperty - pointer to resource property
- * @param resourceProperties - property to be enabled/disabled
- * @param enable - 0:disable, 1:enable
- *
- * @return
- * OCStackResult
- */
#ifdef WITH_PRESENCE
OCStackResult OCChangeResourceProperty(OCResourceProperty * inputProperty,
OCResourceProperty resourceProperties, uint8_t enable)
}
#endif
-/**
- * Initialize resource data structures, variables, etc.
- *
- * @return
- * OCStackResult
- */
OCStackResult initResources()
{
OCStackResult result = OC_STACK_OK;
return result;
}
-/**
- * Add a resource to the end of the linked list of resources.
- *
- * @param resource - resource to be added
- */
void insertResource(OCResource *resource)
{
if (!headResource) {
resource->next = NULL;
}
-/**
- * Find a resource in the linked list of resources.
- *
- * @param resource - resource to be found
- * @return
- * NULL - resource not found
- * pointer to resource - pointer to resource that was found in the linked list
- */
OCResource *findResource(OCResource *resource)
{
OCResource *pointer = headResource;
return NULL;
}
-/**
- * Delete all of the resources in the resource list
- */
void deleteAllResources()
{
OCResource *pointer = headResource;
#endif // WITH_PRESENCE
}
-/**
- * Delete the resource from the linked list.
- *
- * @param resource - resource to be deleted
- * @return
- * OC_STACK_ERROR - error
- * OC_STACK_OK - success
- */
OCStackResult deleteResource(OCResource *resource)
{
OCResource *prev = NULL;
return OC_STACK_ERROR;
}
-/**
- * Delete all of the dynamically allocated elements that were created for the resource.
- *
- * @param resource - specified resource
- */
void deleteResourceElements(OCResource *resource)
{
if (!resource)
deleteResourceInterface(resource->rsrcInterface);
}
-/**
- * Delete all of the dynamically allocated elements that were created for the resource type.
- *
- * @param resourceType - specified resource type
- */
void deleteResourceType(OCResourceType *resourceType)
{
OCResourceType *pointer = resourceType;
}
}
-/**
- * Delete all of the dynamically allocated elements that were created for the resource interface.
- *
- * @param resourceInterface - specified resource interface
- */
void deleteResourceInterface(OCResourceInterface *resourceInterface)
{
OCResourceInterface *pointer = resourceInterface;
}
}
-/**
- * Insert a resource type into a resource's resource type linked list.
- * If resource type already exists, it will not be inserted and the
- * resourceType will be free'd.
- * resourceType->next should be null to avoid memory leaks.
- * Function returns silently for null args..
- * @param resource - resource where resource type is to be inserted
- * @param resourceType - resource type to be inserted
- */
void insertResourceType(OCResource *resource, OCResourceType *resourceType)
{
OCResourceType *pointer = NULL;
resourceType->next = NULL;
}
-/**
- * Get a resource type at the specified index within a resource.
- *
- * @param handle - handle of resource
- * @param index - index of resource type
- *
- * @return
- * resourcetype - if found
- * NULL - not found
- */
OCResourceType *findResourceTypeAtIndex(OCResourceHandle handle, uint8_t index)
{
OCResource *resource = NULL;
return pointer;
}
-/**
- * Finds a resource type in an OCResourceType link-list.
- *
- * @param resourceTypeList - the link-list to be searched through
- * @param resourceTypeName - the key to search for
- *
- * @return
- * resourceType that matches the key (ie. resourceTypeName)
- * NULL - either an invalid parameter or this function was unable to find the key.
- */
OCResourceType *findResourceType(OCResourceType * resourceTypeList, const char * resourceTypeName)
{
if(resourceTypeList && resourceTypeName)
}
return NULL;
}
-/**
- * Insert a resource interface into a resource's resource interface linked list.
- * If resource interface already exists, it will not be inserted and the
- * resourceInterface will be free'd.
- * resourceInterface->next should be null to avoid memory leaks.
- * @param resource - resource where resource interface is to be inserted
- * @param resourceInterface - resource interface to be inserted
- */
+
void insertResourceInterface(OCResource *resource,
OCResourceInterface *resourceInterface)
{
resourceInterface->next = NULL;
}
-/**
- * Get a resource interface at the specified index within a resource.
- *
- * @param handle - handle of resource
- * @param index - index of resource interface
- *
- * @return
- * resourceinterface - if found
- * NULL - not found
- */
OCResourceInterface *findResourceInterfaceAtIndex(OCResourceHandle handle,
uint8_t index)
{
return pointer;
}
-/**
- * Determine if a request/response must be sent in a block transfer because it is too large to be
- * sent in a single PDU. This function can be used for either a request or a response
- *
- * @param request - NULL or pointer to request
- * @param response - NULL or pointer to response
- * @param size - 0 or size of the request/response. If 0, strlen is used for determining
- * the length of the request/response
- *
- * @return
- * false - packet transfer NOT required (i.e. normal request/response)
- * true - packet transfer required (i.e. block transfer needed)
- */
bool OCIsPacketTransferRequired(const char *request, const char *response, size_t size)
{
bool result = false;
return result;
}
-/**
- * Retrieves a resource type based upon a query contains only just one
- * resource attribute (and that has to be of type "rt").
- *
- * @remark This API malloc's memory for the resource type. Do not malloc resourceType
- * before passing in.
- *
- * @param query - The query part of the URI
- * @param resourceType - The resource type to be populated; pass by reference.
- *
- * @return
- * OC_STACK_INVALID_PARAM - Returns this if the resourceType parameter is invalid/NULL.
- * OC_STACK_OK - Success
- */
OCStackResult getResourceType(const char * query, char** resourceType)
{
if(!query)
return result;
}
-/**
- * Extract query from a URI
- *
- * @param uri - full URI with query
- * @param query - pointer to string that will contain query
- * @param newURI - pointer to string that will contain URI
- * @return
- * OCStackResult
- */
OCStackResult getQueryFromUri(const char * uri, char** query, char ** newURI)
{
if(!uri)
return OC_STACK_NO_MEMORY;
}
-/**
- * Return a server instance ID
- *
- * @return
- * ServerID
- */
const ServerID OCGetServerInstanceID(void)
{
static bool generated = false;
return sid;
}
-/**
- * Return a server instance ID string
- * @return
- * Server instance ID string
- */
const char* OCGetServerInstanceIDString(void)
{
// max printed length of a base 10
return buffer;
}
-/// Retrieve the IPv4 address embedded inside OCDev address data structure
int32_t OCDevAddrToIPv4Addr(OCDevAddr *ipAddr, uint8_t *a, uint8_t *b,
uint8_t *c, uint8_t *d )
{
return OC_STACK_OK;
}
-
-/// Retrieve the IPv4 address embedded inside OCDev address data structure
int32_t OCDevAddrToPort(OCDevAddr *ipAddr, uint16_t *port)
{
if ( !ipAddr || !port )
return OC_STACK_OK;
}
-/*
- * Attempts to initialize every network interface that the CA Layer might have compiled in.
- *
- * Note: At least one interface must succeed to initialize. If all calls to @ref CASelectNetwork
- * return something other than @ref CA_STATUS_OK, then this function fails.
- *
- * @return
- * CA_STATUS_OK - Success
- * CA_NOT_SUPPORTED or CA_STATUS_FAILED - None of the transports successfully initialized.
- */
CAResult_t OCSelectNetwork()
{
CAResult_t retResult = CA_STATUS_FAILED;
return retResult;
}
-/**
- * Takes a @ref CAResult_t and converts it to a similar or equivalent @ref OCStackResult value.
- *
- * @return @ref OCStackResult - The equivalent or similar result code to the in-param caResult.
- */
OCStackResult CAResultToOCResult(CAResult_t caResult)
{
switch (caResult)
projects / platform / upstream / iotivity.git / commitdiff