resource/csdk/stack/include/internal/ocserverrequest.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21
  22 /**
  23  * @file
  24  *
  25  * This file contains the definition, types and interfaces for server request
  26  *
  27  */
  28
  29 #ifndef OC_SERVER_REQUEST_H
  30 #define OC_SERVER_REQUEST_H
  31
  32 #include "cacommon.h"
  33 #include "cainterface.h"
  34
  35 /**
  36  * The signature of the internal call back functions to handle responses from entity handler
  37  */
  38 typedef OCStackResult (* OCEHResponseHandler)(OCEntityHandlerResponse * ehResponse);
  39
  40 /**
  41  * following structure will be created in occoap and passed up the stack on the server side.
  42  */
  43 typedef struct OCServerRequest
  44 {
  45     /** The REST method retrieved from received request PDU.*/
  46     OCMethod method;
  47
  48     /** Accept format retrieved from the received request PDU. */
  49     OCPayloadFormat acceptFormat;
  50
  51     /** resourceUrl will be filled in occoap using the path options in received request PDU.*/
  52     char resourceUrl[MAX_URI_LENGTH];
  53
  54     /** resource query send by client.*/
  55     char query[MAX_QUERY_LENGTH];
  56
  57     /** qos is indicating if the request is CON or NON.*/
  58     OCQualityOfService qos;
  59
  60     /** Observe option field.*/
  61     uint32_t observationOption;
  62
  63     /** Observe Result field.*/
  64     OCStackResult observeResult;
  65
  66     /** number of Responses.*/
  67     uint8_t numResponses;
  68
  69     /** Response Entity Handler .*/
  70     OCEHResponseHandler ehResponseHandler;
  71
  72     /** Remote endpoint address **/
  73     OCDevAddr devAddr;
  74
  75     /** The ID of server request*/
  76     uint32_t requestId;
  77
  78     /** Token for the request.*/
  79     CAToken_t requestToken;
  80
  81     /** token length the request.*/
  82     uint8_t tokenLength;
  83
  84     /** The ID of CoAP pdu (Kept in CoAp).*/
  85     uint16_t coapID;
  86
  87     /** For Delayed Response.*/
  88     uint8_t delayedResNeeded;
  89
  90     /** Number of vendor specific header options.*/
  91     uint8_t numRcvdVendorSpecificHeaderOptions;
  92
  93     /** An Array  of received vendor specific header options.*/
  94     OCHeaderOption *rcvdVendorSpecificHeaderOptions;
  95
  96     /** Request to complete.*/
  97     uint8_t requestComplete;
  98
  99     /** Linked list; for multiple server request.*/
 100     struct OCServerRequest * next;
 101
 102     /** Flag indicating slow response.*/
 103     uint8_t slowFlag;
 104
 105     /** Flag indicating notification.*/
 106     uint8_t notificationFlag;
 107
 108     /** Payload Size.*/
 109     size_t payloadSize;
 110
 111     /** payload is retrieved from the payload of the received request PDU.*/
 112     uint8_t payload[1];
 113
 114     // WARNING: Do NOT add attributes after payload as they get overwritten
 115     // when payload content gets copied over!
 116
 117 } OCServerRequest;
 118
 119 /**
 120  * Following structure will be created in ocstack to aggregate responses
 121  * (in future: for block transfer).
 122  */
 123 typedef struct OCServerResponse {
 124
 125     /** Linked list; for multiple server response.*/
 126     struct OCServerResponse * next;
 127
 128     /** this is the pointer to server payload data to be transferred.*/
 129     OCPayload* payload;
 130
 131     /** Remaining size of the payload data to be transferred.*/
 132     uint16_t remainingPayloadSize;
 133
 134     /** Requests to handle.*/
 135     OCRequestHandle requestHandle;
 136 } OCServerResponse;
 137
 138 /**
 139  * Handler function for sending a response from a single resource
 140  *
 141  * @param ehResponse   Pointer to the response from the resource.
 142  *
 143  * @return
 144  *     ::OCStackResult
 145  */
 146 OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
 147
 148 /**
 149  * Handler function for sending a response from multiple resources, such as a collection.
 150  * Aggregates responses from multiple resource until all responses are received then sends the
 151  * concatenated response
 152  *
 153  * TODO: Need to add a timeout in case a (remote?) resource does not respond
 154  *
 155  * @param ehResponse      Pointer to the response from the resource.
 156  *
 157  * @return
 158  *     ::OCStackResult
 159  */
 160 OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
 161
 162 /**
 163  * Get a server request from the server request list using the specified token.
 164  *
 165  * @param token            Token of server request.
 166  * @param tokenLength      Length of token.
 167  *
 168  * @return
 169  *     OCServerRequest*
 170  */
 171 OCServerRequest * GetServerRequestUsingToken (const CAToken_t token, uint8_t tokenLength);
 172
 173 /**
 174  * Get a server request from the server request list using the specified handle
 175  *
 176  * @param handle    Handle of server request.
 177  * @return
 178  *     OCServerRequest*
 179  */
 180 OCServerRequest * GetServerRequestUsingHandle (const OCRequestHandle handle);
 181
 182 /**
 183  * Get a server response from the server response list using the specified handle
 184  *
 185  * @param handle    handle of server response.
 186  *
 187  * @return
 188  *     OCServerResponse*
 189  */
 190 OCServerResponse * GetServerResponseUsingHandle (const OCRequestHandle handle);
 191
 192 /**
 193  * Add a server request to the server request list
 194  *
 195  * @param request                               Initialized server request that is created by this function.
 196  * @param coapID                                ID of CoAP pdu.
 197  * @param delayedResNeeded                      Delayed response required 0=no 1=yes.
 198  * @param notificationFlag                      TODO: remove - does not appear to be used any longer.
 199  * @param method                                RESTful method.
 200  * @param numRcvdVendorSpecificHeaderOptions    Number of received vendor specific header options.
 201  * @param observationOption                     Value of observation option.
 202  * @param qos                                   Request QOS.
 203  * @param query                                 Request query.
 204  * @param rcvdVendorSpecificHeaderOptions       Received vendor specific header options.
 205  * @param reqJSONPayload                        Request JSON payload.
 206  * @param requestToken                          Request token.
 207  * @param tokenLength                           Request token length.
 208  * @param resourceUrl                           URL of resource.
 209  * @param reqTotalSize                          Total size of the request.
 210  * @param acceptFormat                          The format requested for the payload encoding.
 211  * @param devAddr                               Device Address.
 212  *
 213  * @return
 214  *     ::OCStackResult
 215  */
 216 OCStackResult AddServerRequest (OCServerRequest ** request, uint16_t coapID,
 217         uint8_t delayedResNeeded, uint8_t notificationFlag, OCMethod method,
 218         uint8_t numRcvdVendorSpecificHeaderOptions, uint32_t observationOption,
 219         OCQualityOfService qos, char * query,
 220         OCHeaderOption * rcvdVendorSpecificHeaderOptions,
 221         uint8_t * payload, CAToken_t requestToken,
 222         uint8_t tokenLength,
 223         char * resourceUrl, size_t reqTotalSize,
 224         OCPayloadFormat acceptFormat,
 225         const OCDevAddr *devAddr);
 226
 227 /**
 228  * Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
 229  *
 230  * @param entityHandlerRequest      pointer to the OCEntityHandlerRequest struct that is created.
 231  * @param request                   Request handle.
 232  * @param method                    RESTful method.
 233  * @param resource                  Resource handle.
 234  * @param queryBuf                  Resource query of request.
 235  * @param bufReqPayload             JSON payload of request.
 236  * @param numVendorOptions          Number of vendor options.
 237  * @param vendorOptions             Vendor options.
 238  * @param observeAction             Observe action flag.
 239  * @param observeID                 Observe ID.
 240  *
 241  * @return
 242  *     OCStackResult
 243  */
 244 OCStackResult FormOCEntityHandlerRequest(
 245         OCEntityHandlerRequest * entityHandlerRequest,
 246         OCRequestHandle request,
 247         OCMethod method,
 248         OCDevAddr *endpoint,
 249         OCResourceHandle resource,
 250         char * queryBuf,
 251         OCPayloadType payloadType,
 252         uint8_t * payload,
 253         size_t payloadSize,
 254         uint8_t numVendorOptions,
 255         OCHeaderOption * vendorOptions,
 256         OCObserveAction observeAction,
 257         OCObservationId observeID,
 258         uint16_t messageID);
 259
 260 /**
 261  * Find a server request in the server request list and delete
 262  *
 263  * @param serverRequest       server request to find and delete.
 264  */
 265 void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
 266
 267 #endif //OC_SERVER_REQUEST_H
 268