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 #ifndef OC_SERVER_REQUEST_H
  22 #define OC_SERVER_REQUEST_H
  23
  24 #include "cacommon.h"
  25 #include "cainterface.h"
  26 /**
  27  * The signature of the internal call back functions to handle responses from entity handler
  28  */
  29 typedef OCStackResult (* OCEHResponseHandler)(OCEntityHandlerResponse * ehResponse);
  30
  31 // following structure will be created in occoap and passed up the stack on the server side
  32 typedef struct OCServerRequest
  33 {
  34     // the REST method retrieved from received request PDU
  35     OCMethod method;
  36     // resourceUrl will be filled in occoap using the path options in received request PDU
  37     char resourceUrl[MAX_URI_LENGTH];
  38     // resource query send by client
  39     char query[MAX_QUERY_LENGTH];
  40
  41     // qos is indicating if the request is CON or NON
  42     OCQualityOfService qos;
  43     // Observe option field
  44     uint32_t observationOption;
  45     OCStackResult observeResult;
  46     uint8_t numResponses;
  47     OCEHResponseHandler ehResponseHandler;
  48     /** Remote endpoint address **/
  49     OCDevAddr devAddr;
  50     // token for the request
  51     CAToken_t requestToken;
  52     // token length the request
  53     uint8_t tokenLength;
  54     // The ID of CoAP pdu                                   //Kept in
  55     uint16_t coapID;                                        //CoAP
  56     uint8_t delayedResNeeded;
  57     //////////////////////////////////////////////////////////
  58     // An array of the received vendor specific header options
  59     uint8_t numRcvdVendorSpecificHeaderOptions;
  60     OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
  61     uint8_t requestComplete;
  62     struct OCServerRequest * next;
  63     // Flag indicating slow response
  64     uint8_t slowFlag;
  65     uint8_t notificationFlag;
  66     size_t payloadSize;
  67     // payload is retrieved from the payload of the received request PDU
  68     uint8_t payload[1];
  69 } OCServerRequest;
  70
  71 // following structure will be created in ocstack to aggregate responses (in future: for block transfer)
  72 typedef struct OCServerResponse {
  73     struct OCServerResponse * next;
  74     // this is the pointer to server payload data to be transferred
  75     OCPayload* payload;
  76     OCRequestHandle requestHandle;
  77 } OCServerResponse;
  78
  79 /**
  80  * Handler function for sending a response from a single resource
  81  *
  82  * @param ehResponse - pointer to the response from the resource
  83  *
  84  * @return
  85  *     OCStackResult
  86  */
  87 OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
  88
  89 /**
  90  * Handler function for sending a response from multiple resources, such as a collection.
  91  * Aggregates responses from multiple resource until all responses are received then sends the
  92  * concatenated response
  93  *
  94  * TODO: Need to add a timeout in case a (remote?) resource does not respond
  95  *
  96  * @param ehResponse - pointer to the response from the resource
  97  *
  98  * @return
  99  *     OCStackResult
 100  */
 101 OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
 102
 103 /**
 104  * Get a server request from the server request list using the specified token.
 105  *
 106  * @param token - token of server request
 107  * @param tokenLength - length of token
 108  *
 109  * @return
 110  *     OCServerRequest*
 111  */
 112 OCServerRequest * GetServerRequestUsingToken (const CAToken_t token, uint8_t tokenLength);
 113
 114 /**
 115  * Get a server request from the server request list using the specified handle
 116  *
 117  * @param handle - handle of server request
 118  * @return
 119  *     OCServerRequest*
 120  */
 121 OCServerRequest * GetServerRequestUsingHandle (const OCServerRequest * handle);
 122
 123 /**
 124  * Get a server response from the server response list using the specified handle
 125  *
 126  * @param handle - handle of server response
 127  *
 128  * @return
 129  *     OCServerResponse*
 130  */
 131 OCServerResponse * GetServerResponseUsingHandle (const OCServerRequest * handle);
 132
 133 /**
 134  * Add a server request to the server request list
 135  *
 136  * @param request - initialized server request that is created by this function
 137  * @param coapID - ID of CoAP pdu
 138  * @param delayedResNeeded - delayed response required 0=no 1=yes
 139  * @param secured - secure endpoint 0=no 1=yes
 140  * @param notificationFlag - //TODO: remove - does not appear to be used any longer
 141  * @param method - RESTful method
 142  * @param numRcvdVendorSpecificHeaderOptions - number of received vendor specific header options
 143  * @param observationOption - value of observation option
 144  * @param qos - request QOS
 145  * @param query - request query
 146  * @param rcvdVendorSpecificHeaderOptions - received vendor specific header options
 147  * @param reqJSONPayload - request JSON payload
 148  * @param requestToken - request token
 149  * @param tokenLength - request token length
 150  * @param resourceUrl - URL of resource
 151  * @param reqTotalSize - total size of the request
 152  * @param devAddr - OCDevAddr
 153  *
 154  * @return
 155  *     OCStackResult
 156  */
 157 OCStackResult AddServerRequest (OCServerRequest ** request, uint16_t coapID,
 158         uint8_t delayedResNeeded, uint8_t notificationFlag, OCMethod method,
 159         uint8_t numRcvdVendorSpecificHeaderOptions, uint32_t observationOption,
 160         OCQualityOfService qos, char * query,
 161         OCHeaderOption * rcvdVendorSpecificHeaderOptions,
 162         uint8_t * payload, CAToken_t requestToken,
 163         uint8_t tokenLength,
 164         char * resourceUrl, size_t reqTotalSize,
 165         const OCDevAddr *devAddr);
 166
 167 /**
 168  * Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
 169  *
 170  * @param entityHandlerRequest - pointer to the OCEntityHandlerRequest struct that is created
 171  * @param request          - request handle
 172  * @param method           - RESTful method
 173  * @param endpoint         - requesting endpoint
 174  * @param resource         - resource handle
 175  * @param queryBuf         - resource query of request
 176  * @param payload          - payload of request
 177  * @param payloadSize      - size of the payload request
 178  * @param numVendorOptions - number of vendor options
 179  * @param vendorOptions    - vendor options
 180  * @param observeAction    - observe action flag
 181  * @param observeID        - observe ID
 182  *
 183  * @return
 184  *     OCStackResult
 185  */
 186 OCStackResult FormOCEntityHandlerRequest(
 187                                 OCEntityHandlerRequest *entityHandlerRequest,
 188                                 OCRequestHandle request,
 189                                 OCMethod method,
 190                                 OCDevAddr *endpoint,
 191                                 OCResourceHandle resource,
 192                                 char *queryBuf,
 193                                 uint8_t *payload,
 194                                 size_t payloadSize,
 195                                 uint8_t numVendorOptions,
 196                                 OCHeaderOption *vendorOptions,
 197                                 OCObserveAction observeAction,
 198                                 OCObservationId observeID);
 199
 200 /**
 201  * Find a server request in the server request list and delete
 202  *
 203  * @param serverRequest - server request to find and delete
 204  */
 205 void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
 206
 207 #endif //OC_SERVER_REQUEST_H
 208