1 //******************************************************************
3 // Copyright 2014 Intel Corporation All Rights Reserved.
4 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
9 #include <netinet/ip.h>
19 //-----------------------------------------------------------------------------
21 //-----------------------------------------------------------------------------
23 //May want to refactor this in upcoming sprints. Don't want to expose to application layer that lower level stack is using CoAP.
24 #define OC_WELL_KNOWN_QUERY PCF("coap://224.0.1.187:5683/.well-known/core")
25 #define OC_EXPLICIT_DEVICE_DISCOVERY_URI PCF("coap://224.0.1.187:5683/oc/core?rt=core.led")
27 #define USE_RANDOM_PORT (0)
28 #define MAX_TOKEN_LENGTH (8)
29 #define MAX_RESPONSE_LENGTH (128)
30 #define MAX_REQUEST_LENGTH (128)
31 #define MAX_URI_LENGTH (64)
32 #define MAX_QUERY_LENGTH (64)
33 #define MAX_CONTAINED_RESOURCES (5)
35 //-----------------------------------------------------------------------------
37 //-----------------------------------------------------------------------------
40 * Standard RESTful HTTP Methods
44 OC_REST_GET = (1 << 0), // Read
45 OC_REST_PUT = (1 << 1), // Write
46 OC_REST_POST = (1 << 2), // Update
47 OC_REST_DELETE = (1 << 3), // Delete
48 OC_REST_OBSERVE = (1 << 4) // Register observe request
52 * Host Mode of Operation
64 OC_NON_CONFIRMABLE = 0,
72 OC_ACTIVE = (1 << 0), // set == initialized; unset == deleted
73 OC_DISCOVERABLE = (1 << 1), // Discovery of this resource allowed
74 OC_OBSERVABLE = (1 << 2), // Observe allowed
75 OC_SLOW = (1 << 3) // Expect delay in processing requests. Send ACK to request and send response later
79 * Declares Stack Results & Errors
84 OC_STACK_INVALID_QUERY,
86 OC_STACK_INVALID_PORT,
87 OC_STACK_INVALID_CALLBACK,
88 OC_STACK_INVALID_METHOD,
91 OC_STACK_INVALID_PARAM,
93 OC_STACK_NO_RESOURCE, /* resource not found*/
94 OC_STACK_RESOURCE_ERROR, /*ex: not supported method or interface*/
95 OC_STACK_SLOW_RESOURCE,
100 * Handle to an OCResource object owned by the OCStack.
102 typedef void * OCResourceHandle;
105 uint8_t token[MAX_TOKEN_LENGTH];
110 * Incoming requests handled by the server. Requests are passed in as a parameter to the @ref OCEntityHandler callback API.
111 * @brief The @ref OCEntityHandler callback API must be implemented in the application in order to receive these requests.
114 // Associated resource
115 OCResourceHandle resource;
116 // the REST method retrieved from received request PDU
118 // reqJSON is retrieved from the payload of the received request PDU
119 unsigned const char * reqJSONPayload;
120 // token is copied from the received request PDU
122 // resJSON is allocated in the stack and will be used by entity handler to fill in its response
123 unsigned char * resJSONPayload;
124 // Length of maximum allowed response
125 uint16_t resJSONPayloadLen;
126 }OCEntityHandlerRequest;
129 * Response from queries to remote servers. Queries are made by calling the @ref OCDoResource API.
132 // the is the result of our stack, OCStackResult should contain coap/other error codes;
133 OCStackResult result;
134 // Address of remote server
136 // reqJSON is retrieved from the payload of the received request PDU
137 unsigned const char * resJSONPayload;
141 OC_INIT_FLAG = (1 << 0),
142 OC_REQUEST_FLAG = (1 << 1),
143 OC_OBSERVE_FLAG = (1 << 2)
144 } OCEntityHandlerFlag; //entity_handler_flag_t ;
146 // possible returned values from client application
148 OC_STACK_DELETE_TRANSACTION = 0,
149 OC_STACK_KEEP_TRANSACTION
150 } OCStackApplicationResult;
152 //-----------------------------------------------------------------------------
153 // Callback function definitions
154 //-----------------------------------------------------------------------------
155 typedef OCStackApplicationResult (* OCClientApplicationCBType)(void *ctx, OCClientResponse * clientResponse);
159 OCClientApplicationCBType cb;
163 * Application server implementations must implement this callback to consume requests OTA.
165 typedef void (*OCEntityHandler) (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
168 //-----------------------------------------------------------------------------
169 // Function prototypes
170 //-----------------------------------------------------------------------------
173 * Initialize the OC Stack. Must be called prior to starting the stack.
176 * IP Address of host device
178 * Port of host device
180 * Host device is client, server, or client-server
183 * OC_STACK_OK - no errors
184 * OC_STACK_ERROR - stack init error
186 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
189 * Stop the OC stack. Use for a controlled shutdown.
191 * OC_STACK_OK - no errors
192 * OC_STACK_ERROR - stack not initialized
194 OCStackResult OCStop();
197 * Called in main loop of OC client or server. Allows low-level processing of
201 * OC_STACK_OK - no errors
202 * OC_STACK_ERROR - stack process error
204 OCStackResult OCProcess();
207 * Discover OC resources.
209 * @param method - method to perform on the resource
210 * @param requiredUri - URI of the resource to interact with
211 * @param referenceUri - URI of the reference resource
212 * @param request - JSON encoded request
213 * @param qos - quality of service
214 * @param clientApplicationCB- asynchronous callback function that is invoked
215 * by the stack when discovery or resource interaction is complete
218 * OC_STACK_OK - no errors
219 * OC_STACK_INVALID_CALLBACK - invalid callback function pointer
220 * OC_STACK_INVALID_METHOD - invalid resource method
221 * OC_STACK_INVALID_URI - invalid required or reference URI
223 OCStackResult OCDoResource(OCMethod method, const char *requiredUri, const char *referenceUri,
224 // const char *request, OCQualityOfService qos, OCClientApplicationCBType clientApplicationCB);
225 const char *request, OCQualityOfService qos, OCCallbackData *cbData);
232 * @param handle - pointer to handle to newly created resource. Set by ocstack. Used to refer to resource
233 * @param resourceTypeName - name of resource type. Example: "core.led"
234 * @param resourceAttributeRepresentation - attribute representation. list of attributes:type, with each pair
235 * separated by semicolons. Example: "state:oc.bt.b;power:oc.bt.i"
236 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
237 * @param allowedMethods - methods permitted on interface. Example: OC_REST_GET|OC_REST_PUT
238 * @param uri - URI of the resource. Example: "/a/led"
239 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
240 * @param resourceProperties - properties supported by resource. Example: OC_DISCOVERABLE|OC_OBSERVABLE
243 * OC_STACK_OK - no errors
244 * OC_STACK_ERROR - stack process error
246 OCStackResult OCCreateResource(OCResourceHandle *handle,
247 const char *resourceTypeName,
248 const char *resourceAttributeRepresentation,
249 const char *resourceInterfaceName,
250 uint8_t allowedMethods,
252 OCEntityHandler entityHandler,
253 uint8_t resourceProperties);
256 * Add a resource to a container resource.
258 * @param containerHandle - handle to the container resource
259 * @param addedResourceHandle - handle to resource to be added to the container resource
262 * OC_STACK_OK - no errors
263 * OC_STACK_ERROR - stack process error
265 OCStackResult OCBindContainedResourceToResource(OCResourceHandle containerHandle, OCResourceHandle addedResourceHandle);
268 * Bind a resourcetype to a resource.
270 * @param handle - handle to the container resource
271 * @param resourceTypeName - name of resource type. Example: "core.led"
272 * @param resourceAttributeRepresentation - attribute representation. list of attributes:type, with each pair
273 * separated by semicolons. Example: "state:oc.bt.b;power:oc.bt.i"
276 * OC_STACK_OK - no errors
277 * OC_STACK_ERROR - stack process error
279 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
280 const char *resourceTypeName,
281 const char *resourceAttributeRepresentation);
283 * Bind a resource interface to a resource.
285 * @param handle - handle to the container resource
286 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
287 * @param allowedMethods - methods permitted on interface. Example: OC_REST_GET|OC_REST_PUT
290 * OC_STACK_OK - no errors
291 * OC_STACK_ERROR - stack process error
293 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
294 const char *resourceInterfaceName,
295 uint8_t allowedMethods);
298 * Bind an entity handler to the resource.
300 * @param handle - handle to the resource that the contained resource is to be bound
301 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
303 * OC_STACK_OK - no errors
304 * OC_STACK_ERROR - stack process error
306 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
309 * Get the number of resources that have been created in the stack.
311 * @param numResources - pointer to count variable
314 * OC_STACK_OK - no errors
315 * OC_STACK_ERROR - stack process error
318 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
321 * Get a resource handle by index.
323 * @param index - index of resource, 0 to Count - 1
326 * Resource handle - if found
327 * NULL - if not found
329 OCResourceHandle OCGetResourceHandle(uint8_t index);
332 * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
335 * @param handle - handle of resource to be deleted
338 * OC_STACK_OK - no errors
339 * OC_STACK_ERROR - stack process error
341 OCStackResult OCDeleteResource(OCResourceHandle handle);
344 * Get the URI of the resource specified by handle.
346 * @param handle - handle of resource
348 * URI string - if resource found
349 * NULL - resource not found
351 const char *OCGetResourceUri(OCResourceHandle handle);
354 * Get the properties of the resource specified by handle.
355 * NOTE: that after a resource is created, the OC_ACTIVE property is set
356 * for the resource by the stack.
358 * @param handle - handle of resource
360 * property bitmap - if resource found
361 * NULL - resource not found
363 uint8_t OCGetResourceProperties(OCResourceHandle handle);
366 * Get the number of resource types of the resource.
368 * @param handle - handle of resource
369 * @param numResourceTypes - pointer to count variable
372 * OC_STACK_OK - no errors
373 * OC_STACK_ERROR - stack process error
375 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
378 * Get name of resource type of the resource.
380 * @param handle - handle of resource
381 * @param index - index of resource, 0 to Count - 1
384 * resource type name - if resource found
385 * NULL - resource not found
387 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
390 * Get attributes of resource type of the resource.
392 * @param handle - handle of resource
393 * @param index - index of resource, 0 to Count - 1
396 * resource type attributes - if resource found
397 * NULL - resource not found
399 const char *OCGetResourceAttributeRepresentation(OCResourceHandle handle, uint8_t index);
402 * Get the number of resource interfaces of the resource.
404 * @param handle - handle of resource
405 * @param numResources - pointer to count variable
408 * OC_STACK_OK - no errors
409 * OC_STACK_ERROR - stack process error
412 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
415 * Get name of resource interface of the resource.
417 * @param handle - handle of resource
418 * @param index - index of resource, 0 to Count - 1
421 * resource interface name - if resource found
422 * NULL - resource not found
424 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
427 * Get methods of resource interface of the resource.
429 * @param handle - handle of resource
430 * @param index - index of resource, 0 to Count - 1
433 * allowed methods - if resource found
434 * NULL - resource not found
436 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
439 * Get name of resource interface of the resource.
441 * @param containerHandle - handle of container resource
442 * @param index - index of contained resource, 0 to Count - 1
445 * handle to contained resource - if resource found
446 * NULL - resource not found
448 OCResourceHandle OCGetContainedResourceHandle(OCResourceHandle containerHandle, uint8_t index);
451 * Get the entity handler for a resource.
453 * @param handle - handle of resource
456 * entity handler - if resource found
457 * NULL - resource not found
459 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
462 * Notify observers that an observed value has changed.
464 * **NOTE: This API has NOT been finalized!!!**
466 * @param handle - handle of resource
469 * OC_STACK_OK - no errors
470 * OC_STACK_ERROR - stack not initialized
472 OCStackResult OCNotifyObservers(OCResourceHandle handle);
476 #endif // __cplusplus
478 #endif /* OCSTACK_H_ */