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