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