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