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
  62     uint32_t observationOption;
  63
  64     /** Observe Result field.*/
  65     OCStackResult observeResult;
  66
  67     /** number of Responses.*/
  68     uint8_t numResponses;
  69
  70     /** Response Entity Handler .*/
  71     OCEHResponseHandler ehResponseHandler;
  72
  73     /** Remote endpoint address **/
  74     OCDevAddr devAddr;
  75
  76     /** Token for the request.*/
  77     CAToken_t requestToken;
  78
  79     /** token length the request.*/
  80     uint8_t tokenLength;
  81
  82     /** The ID of CoAP pdu (Kept in CoAp).*/
  83     uint16_t coapID;
  84
  85     /** For Delayed Response.*/
  86     uint8_t delayedResNeeded;
  87
  88     /** Number of vendor specific header options.*/
  89     uint8_t numRcvdVendorSpecificHeaderOptions;
  90
  91     /** An Array  of received vendor specific header options.*/
  92     OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
  93
  94     /** Request to complete.*/
  95     uint8_t requestComplete;
  96
  97     /** Linked list; for multiple server request.*/
  98     struct OCServerRequest * next;
  99
 100     /** Flag indicating slow response.*/
 101     uint8_t slowFlag;
 102
 103     /** Flag indicating notification.*/
 104     uint8_t notificationFlag;
 105
 106     /** Payload Size.*/
 107     size_t payloadSize;
 108
 109     /** payload is retrieved from the payload of the received request PDU.*/
 110     uint8_t payload[1];
 111
 112     // WARNING: Do NOT add attributes after payload as they get overwritten
 113     // when payload content gets copied over!
 114
 115 } OCServerRequest;
 116
 117 /**
 118  * Following structure will be created in ocstack to aggregate responses
 119  * (in future: for block transfer).
 120  */
 121 typedef struct OCServerResponse {
 122
 123     /** Linked list; for multiple server response.*/
 124     struct OCServerResponse * next;
 125
 126     /** this is the pointer to server payload data to be transferred.*/
 127     OCPayload* payload;
 128
 129     /** Remaining size of the payload data to be transferred.*/
 130     uint16_t remainingPayloadSize;
 131
 132     /** Requests to handle.*/
 133     OCRequestHandle requestHandle;
 134 } OCServerResponse;
 135
 136 /**
 137  * Handler function for sending a response from a single resource
 138  *
 139  * @param ehResponse   Pointer to the response from the resource.
 140  *
 141  * @return
 142  *     ::OCStackResult
 143  */
 144 OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
 145
 146 /**
 147  * Handler function for sending a response from multiple resources, such as a collection.
 148  * Aggregates responses from multiple resource until all responses are received then sends the
 149  * concatenated response
 150  *
 151  * TODO: Need to add a timeout in case a (remote?) resource does not respond
 152  *
 153  * @param ehResponse      Pointer to the response from the resource.
 154  *
 155  * @return
 156  *     ::OCStackResult
 157  */
 158 OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
 159
 160 /**
 161  * Get a server request from the server request list using the specified token.
 162  *
 163  * @param token            Token of server request.
 164  * @param tokenLength      Length of token.
 165  *
 166  * @return
 167  *     OCServerRequest*
 168  */
 169 OCServerRequest * GetServerRequestUsingToken (const CAToken_t token, uint8_t tokenLength);
 170
 171 /**
 172  * Get a server request from the server request list using the specified handle
 173  *
 174  * @param handle    Handle of server request.
 175  * @return
 176  *     OCServerRequest*
 177  */
 178 OCServerRequest * GetServerRequestUsingHandle (const OCServerRequest * handle);
 179
 180 /**
 181  * Get a server response from the server response list using the specified handle
 182  *
 183  * @param handle    handle of server response.
 184  *
 185  * @return
 186  *     OCServerResponse*
 187  */
 188 OCServerResponse * GetServerResponseUsingHandle (const OCServerRequest * handle);
 189
 190 /**
 191  * Add a server request to the server request list
 192  *
 193  * @param request                               Initialized server request that is created by this function.
 194  * @param coapID                                ID of CoAP pdu.
 195  * @param delayedResNeeded                      Delayed response required 0=no 1=yes.
 196  * @param notificationFlag                      TODO: remove - does not appear to be used any longer.
 197  * @param method                                RESTful method.
 198  * @param numRcvdVendorSpecificHeaderOptions    Number of received vendor specific header options.
 199  * @param observationOption                     Value of observation option.
 200  * @param qos                                   Request QOS.
 201  * @param query                                 Request query.
 202  * @param rcvdVendorSpecificHeaderOptions       Received vendor specific header options.
 203  * @param reqJSONPayload                        Request JSON payload.
 204  * @param requestToken                          Request token.
 205  * @param tokenLength                           Request token length.
 206  * @param resourceUrl                           URL of resource.
 207  * @param reqTotalSize                          Total size of the request.
 208  * @param acceptFormat                          The format requested for the payload encoding.
 209  * @param devAddr                               Device Address.
 210  *
 211  * @return
 212  *     ::OCStackResult
 213  */
 214 OCStackResult AddServerRequest (OCServerRequest ** request, uint16_t coapID,
 215         uint8_t delayedResNeeded, uint8_t notificationFlag, OCMethod method,
 216         uint8_t numRcvdVendorSpecificHeaderOptions, uint32_t observationOption,
 217         OCQualityOfService qos, char * query,
 218         OCHeaderOption * rcvdVendorSpecificHeaderOptions,
 219         uint8_t * payload, CAToken_t requestToken,
 220         uint8_t tokenLength,
 221         char * resourceUrl, size_t reqTotalSize,
 222         OCPayloadFormat acceptFormat,
 223         const OCDevAddr *devAddr);
 224
 225 /**
 226  * Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
 227  *
 228  * @param entityHandlerRequest      pointer to the OCEntityHandlerRequest struct that is created.
 229  * @param request                   Request handle.
 230  * @param method                    RESTful method.
 231  * @param resource                  Resource handle.
 232  * @param queryBuf                  Resource query of request.
 233  * @param bufReqPayload             JSON payload of request.
 234  * @param numVendorOptions          Number of vendor options.
 235  * @param vendorOptions             Vendor options.
 236  * @param observeAction             Observe action flag.
 237  * @param observeID                 Observe ID.
 238  *
 239  * @return
 240  *     OCStackResult
 241  */
 242 OCStackResult FormOCEntityHandlerRequest(
 243         OCEntityHandlerRequest * entityHandlerRequest,
 244         OCRequestHandle request,
 245         OCMethod method,
 246         OCDevAddr *endpoint,
 247         OCResourceHandle resource,
 248         char * queryBuf,
 249         OCPayloadType payloadType,
 250         uint8_t * payload,
 251         size_t payloadSize,
 252         uint8_t numVendorOptions,
 253         OCHeaderOption * vendorOptions,
 254         OCObserveAction observeAction,
 255         OCObservationId observeID);
 256
 257 /**
 258  * Find a server request in the server request list and delete
 259  *
 260  * @param serverRequest       server request to find and delete.
 261  */
 262 void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
 263
 264 #endif //OC_SERVER_REQUEST_H
 265