1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
25 * This file contains the definition, types and interfaces for server request
29 #ifndef OC_SERVER_REQUEST_H
30 #define OC_SERVER_REQUEST_H
33 #include "cainterface.h"
36 * The signature of the internal call back functions to handle responses from entity handler
38 typedef OCStackResult (* OCEHResponseHandler)(OCEntityHandlerResponse * ehResponse);
41 * following structure will be created in occoap and passed up the stack on the server side.
43 typedef struct OCServerRequest
45 /** The REST method retrieved from received request PDU.*/
48 /** Accept format retrieved from the received request PDU. */
49 OCPayloadFormat acceptFormat;
51 /** resourceUrl will be filled in occoap using the path options in received request PDU.*/
52 char resourceUrl[MAX_URI_LENGTH];
54 /** resource query send by client.*/
55 char query[MAX_QUERY_LENGTH];
57 /** qos is indicating if the request is CON or NON.*/
58 OCQualityOfService qos;
60 /** Observe option field.*/
62 uint32_t observationOption;
64 /** Observe Result field.*/
65 OCStackResult observeResult;
67 /** number of Responses.*/
70 /** Response Entity Handler .*/
71 OCEHResponseHandler ehResponseHandler;
73 /** Remote endpoint address **/
76 /** Token for the request.*/
77 CAToken_t requestToken;
79 /** token length the request.*/
82 /** The ID of CoAP pdu (Kept in CoAp).*/
85 /** For Delayed Response.*/
86 uint8_t delayedResNeeded;
88 /** Number of vendor specific header options.*/
89 uint8_t numRcvdVendorSpecificHeaderOptions;
91 /** An Array of received vendor specific header options.*/
92 OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
94 /** Request to complete.*/
95 uint8_t requestComplete;
97 /** Linked list; for multiple server request.*/
98 struct OCServerRequest * next;
100 /** Flag indicating slow response.*/
103 /** Flag indicating notification.*/
104 uint8_t notificationFlag;
109 /** payload is retrieved from the payload of the received request PDU.*/
112 // WARNING: Do NOT add attributes after payload as they get overwritten
113 // when payload content gets copied over!
118 * Following structure will be created in ocstack to aggregate responses
119 * (in future: for block transfer).
121 typedef struct OCServerResponse {
123 /** Linked list; for multiple server response.*/
124 struct OCServerResponse * next;
126 /** this is the pointer to server payload data to be transferred.*/
129 /** Remaining size of the payload data to be transferred.*/
130 uint16_t remainingPayloadSize;
132 /** Requests to handle.*/
133 OCRequestHandle requestHandle;
137 * Handler function for sending a response from a single resource
139 * @param ehResponse Pointer to the response from the resource.
144 OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
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
151 * TODO: Need to add a timeout in case a (remote?) resource does not respond
153 * @param ehResponse Pointer to the response from the resource.
158 OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
161 * Get a server request from the server request list using the specified token.
163 * @param token Token of server request.
164 * @param tokenLength Length of token.
169 OCServerRequest * GetServerRequestUsingToken (const CAToken_t token, uint8_t tokenLength);
172 * Get a server request from the server request list using the specified handle
174 * @param handle Handle of server request.
178 OCServerRequest * GetServerRequestUsingHandle (const OCServerRequest * handle);
181 * Get a server response from the server response list using the specified handle
183 * @param handle handle of server response.
188 OCServerResponse * GetServerResponseUsingHandle (const OCServerRequest * handle);
191 * Add a server request to the server request list
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.
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,
221 char * resourceUrl, size_t reqTotalSize,
222 OCPayloadFormat acceptFormat,
223 const OCDevAddr *devAddr);
226 * Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
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.
242 OCStackResult FormOCEntityHandlerRequest(
243 OCEntityHandlerRequest * entityHandlerRequest,
244 OCRequestHandle request,
247 OCResourceHandle resource,
249 OCPayloadType payloadType,
252 uint8_t numVendorOptions,
253 OCHeaderOption * vendorOptions,
254 OCObserveAction observeAction,
255 OCObservationId observeID);
258 * Find a server request in the server request list and delete
260 * @param serverRequest server request to find and delete.
262 void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
264 #endif //OC_SERVER_REQUEST_H