//
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+/**
+ * @file
+ *
+ * This file contains the definition, types and interfaces for server request
+ *
+ */
+
#ifndef OC_SERVER_REQUEST_H
#define OC_SERVER_REQUEST_H
#include "cacommon.h"
#include "cainterface.h"
+
/**
* The signature of the internal call back functions to handle responses from entity handler
*/
typedef OCStackResult (* OCEHResponseHandler)(OCEntityHandlerResponse * ehResponse);
-// following structure will be created in occoap and passed up the stack on the server side
+/**
+ * following structure will be created in occoap and passed up the stack on the server side.
+ */
typedef struct OCServerRequest
{
- // the REST method retrieved from received request PDU
+ /** The REST method retrieved from received request PDU.*/
OCMethod method;
- // resourceUrl will be filled in occoap using the path options in received request PDU
+
+ /** Accept format retrieved from the received request PDU. */
+ OCPayloadFormat acceptFormat;
+
+ /** resourceUrl will be filled in occoap using the path options in received request PDU.*/
char resourceUrl[MAX_URI_LENGTH];
- // resource query send by client
+
+ /** resource query send by client.*/
char query[MAX_QUERY_LENGTH];
- // qos is indicating if the request is CON or NON
+ /** qos is indicating if the request is CON or NON.*/
OCQualityOfService qos;
- // Observe option field
+
+ /** Observe option field.*/
uint32_t observationOption;
+
+ /** Observe Result field.*/
OCStackResult observeResult;
+
+ /** number of Responses.*/
uint8_t numResponses;
+
+ /** Response Entity Handler .*/
OCEHResponseHandler ehResponseHandler;
+
/** Remote endpoint address **/
OCDevAddr devAddr;
- // token for the request
+
+ /** The ID of server request*/
+ uint32_t requestId;
+
+ /** Token for the request.*/
CAToken_t requestToken;
- // token length the request
+
+ /** token length the request.*/
uint8_t tokenLength;
- // The ID of CoAP pdu //Kept in
- uint16_t coapID; //CoAP
+
+ /** The ID of CoAP pdu (Kept in CoAp).*/
+ uint16_t coapID;
+
+ /** For Delayed Response.*/
uint8_t delayedResNeeded;
- //////////////////////////////////////////////////////////
- // An array of the received vendor specific header options
+
+ /** Number of vendor specific header options.*/
uint8_t numRcvdVendorSpecificHeaderOptions;
- OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
+
+ /** An Array of received vendor specific header options.*/
+ OCHeaderOption *rcvdVendorSpecificHeaderOptions;
+
+ /** Request to complete.*/
uint8_t requestComplete;
+
+ /** Linked list; for multiple server request.*/
struct OCServerRequest * next;
- // Flag indicating slow response
+
+ /** Flag indicating slow response.*/
uint8_t slowFlag;
+
+ /** Flag indicating notification.*/
uint8_t notificationFlag;
+
+ /** Payload Size.*/
size_t payloadSize;
- // payload is retrieved from the payload of the received request PDU
+
+ /** payload is retrieved from the payload of the received request PDU.*/
uint8_t payload[1];
+
+ // WARNING: Do NOT add attributes after payload as they get overwritten
+ // when payload content gets copied over!
+
} OCServerRequest;
-// following structure will be created in ocstack to aggregate responses (in future: for block transfer)
+/**
+ * Following structure will be created in ocstack to aggregate responses
+ * (in future: for block transfer).
+ */
typedef struct OCServerResponse {
+
+ /** Linked list; for multiple server response.*/
struct OCServerResponse * next;
- // this is the pointer to server payload data to be transferred
+
+ /** this is the pointer to server payload data to be transferred.*/
OCPayload* payload;
+
+ /** Remaining size of the payload data to be transferred.*/
+ uint16_t remainingPayloadSize;
+
+ /** Requests to handle.*/
OCRequestHandle requestHandle;
} OCServerResponse;
/**
* Handler function for sending a response from a single resource
*
- * @param ehResponse - pointer to the response from the resource
+ * @param ehResponse Pointer to the response from the resource.
*
* @return
- * OCStackResult
+ * ::OCStackResult
*/
OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
*
* TODO: Need to add a timeout in case a (remote?) resource does not respond
*
- * @param ehResponse - pointer to the response from the resource
+ * @param ehResponse Pointer to the response from the resource.
*
* @return
- * OCStackResult
+ * ::OCStackResult
*/
OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
/**
* Get a server request from the server request list using the specified token.
*
- * @param token - token of server request
- * @param tokenLength - length of token
+ * @param token Token of server request.
+ * @param tokenLength Length of token.
*
* @return
* OCServerRequest*
/**
* Get a server request from the server request list using the specified handle
*
- * @param handle - handle of server request
+ * @param handle Handle of server request.
* @return
* OCServerRequest*
*/
-OCServerRequest * GetServerRequestUsingHandle (const OCServerRequest * handle);
+OCServerRequest * GetServerRequestUsingHandle (const OCRequestHandle handle);
/**
* Get a server response from the server response list using the specified handle
*
- * @param handle - handle of server response
+ * @param handle handle of server response.
*
* @return
* OCServerResponse*
*/
-OCServerResponse * GetServerResponseUsingHandle (const OCServerRequest * handle);
+OCServerResponse * GetServerResponseUsingHandle (const OCRequestHandle handle);
/**
* Add a server request to the server request list
*
- * @param request - initialized server request that is created by this function
- * @param coapID - ID of CoAP pdu
- * @param delayedResNeeded - delayed response required 0=no 1=yes
- * @param secured - secure endpoint 0=no 1=yes
- * @param notificationFlag - //TODO: remove - does not appear to be used any longer
- * @param method - RESTful method
- * @param numRcvdVendorSpecificHeaderOptions - number of received vendor specific header options
- * @param observationOption - value of observation option
- * @param qos - request QOS
- * @param query - request query
- * @param rcvdVendorSpecificHeaderOptions - received vendor specific header options
- * @param reqJSONPayload - request JSON payload
- * @param requestToken - request token
- * @param tokenLength - request token length
- * @param resourceUrl - URL of resource
- * @param reqTotalSize - total size of the request
- * @param devAddr - OCDevAddr
+ * @param request Initialized server request that is created by this function.
+ * @param coapID ID of CoAP pdu.
+ * @param delayedResNeeded Delayed response required 0=no 1=yes.
+ * @param notificationFlag TODO: remove - does not appear to be used any longer.
+ * @param method RESTful method.
+ * @param numRcvdVendorSpecificHeaderOptions Number of received vendor specific header options.
+ * @param observationOption Value of observation option.
+ * @param qos Request QOS.
+ * @param query Request query.
+ * @param rcvdVendorSpecificHeaderOptions Received vendor specific header options.
+ * @param reqJSONPayload Request JSON payload.
+ * @param requestToken Request token.
+ * @param tokenLength Request token length.
+ * @param resourceUrl URL of resource.
+ * @param reqTotalSize Total size of the request.
+ * @param acceptFormat The format requested for the payload encoding.
+ * @param devAddr Device Address.
*
* @return
- * OCStackResult
+ * ::OCStackResult
*/
OCStackResult AddServerRequest (OCServerRequest ** request, uint16_t coapID,
uint8_t delayedResNeeded, uint8_t notificationFlag, OCMethod method,
uint8_t * payload, CAToken_t requestToken,
uint8_t tokenLength,
char * resourceUrl, size_t reqTotalSize,
+ OCPayloadFormat acceptFormat,
const OCDevAddr *devAddr);
/**
* Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
*
- * @param entityHandlerRequest - pointer to the OCEntityHandlerRequest struct that is created
- * @param request - request handle
- * @param method - RESTful method
- * @param resource - resource handle
- * @param queryBuf - resource query of request
- * @param payload - payload of request
- * @param payloadSize - size of the payload request
- * @param numVendorOptions - number of vendor options
- * @param vendorOptions - vendor options
- * @param observeAction - observe action flag
- * @param observeID - observe ID
+ * @param entityHandlerRequest pointer to the OCEntityHandlerRequest struct that is created.
+ * @param request Request handle.
+ * @param method RESTful method.
+ * @param resource Resource handle.
+ * @param queryBuf Resource query of request.
+ * @param bufReqPayload JSON payload of request.
+ * @param numVendorOptions Number of vendor options.
+ * @param vendorOptions Vendor options.
+ * @param observeAction Observe action flag.
+ * @param observeID Observe ID.
*
* @return
* OCStackResult
*/
-OCStackResult FormOCEntityHandlerRequest(OCEntityHandlerRequest * entityHandlerRequest,
+OCStackResult FormOCEntityHandlerRequest(
+ OCEntityHandlerRequest * entityHandlerRequest,
OCRequestHandle request,
- OCMethod method, OCResourceHandle resource, char * queryBuf,
- uint8_t * payload, size_t payloadSize,
- uint8_t numVendorOptions, OCHeaderOption * vendorOptions, OCObserveAction observeAction,
- OCObservationId observeID);
+ OCMethod method,
+ OCDevAddr *endpoint,
+ OCResourceHandle resource,
+ char * queryBuf,
+ OCPayloadType payloadType,
+ uint8_t * payload,
+ size_t payloadSize,
+ uint8_t numVendorOptions,
+ OCHeaderOption * vendorOptions,
+ OCObserveAction observeAction,
+ OCObservationId observeID,
+ uint16_t messageID);
/**
* Find a server request in the server request list and delete
*
- * @param serverRequest - server request to find and delete
+ * @param serverRequest server request to find and delete.
*/
void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
projects / platform / upstream / iotivity.git / blobdiff