1 mike 1.1 /*
2 **==============================================================================
3 **
4 ** Open Management Infrastructure (OMI)
5 **
6 ** Copyright (c) Microsoft Corporation
7 **
8 ** Licensed under the Apache License, Version 2.0 (the "License"); you may not
9 ** use this file except in compliance with the License. You may obtain a copy
10 ** of the License at
11 **
12 ** http://www.apache.org/licenses/LICENSE-2.0
13 **
14 ** THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 ** KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
16 ** WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
17 ** MERCHANTABLITY OR NON-INFRINGEMENT.
18 **
19 ** See the Apache 2 License for the specific language governing permissions
20 ** and limitations under the License.
21 **
22 mike 1.1 **==============================================================================
23 */
24
25 #ifndef _omi_http_httpclient_h
26 #define _omi_http_httpclient_h
27
28 #include "config.h"
29 #include <common.h>
30 #include <base/batch.h>
|
32 mike 1.1 #include <sock/selector.h>
33
34 BEGIN_EXTERNC
35
36 /* HTTP Client - internal C interface */
37 typedef struct _HttpClient HttpClient;
38
39 /* array of strings (as declared in mi.h)
40 This strucutre has layout compatible with MI_StringArray
41 and mi::StringA class
42 This structure is used to send request.
43 Sample of usage:
44 const char* header_strings[] = {
45 "Content-Type: text/html;charset=UTF-8",
46 "User-Agent: xplat http client"
47 };
48 HttpClientRequestHeaders headers = {
49 header_strings,
50 MI_COUNT(header_strings) };
51 */
52 typedef struct _HttpClientRequestHeaders
53 mike 1.1 {
54 const char* const* data;
55 MI_Uint32 size;
56 }
57 HttpClientRequestHeaders;
58
59 /*
60 This structure represents one http header field,
61 received from server, as name/value pair.
62 */
63 typedef struct _HttpClientHeaderField
64 {
65 const char* name;
66 const char* value;
67 }
68 HttpClientHeaderField;
69
70 /*
71 This structure provides information about http response.
72 Members:
73 headers: array of name/value pairs
74 mike 1.1 sizeHeaders: number of pair in headers array
75 httpError: http error code. like 200, 400 etc
76 */
77 typedef struct _HttpClientResponseHeader
78 {
79 const HttpClientHeaderField* headers;
80 MI_Uint32 sizeHeaders;
81 MI_Uint32 httpError;
82
83 }
84 HttpClientResponseHeader;
85
86 /* *** Callbacks *** */
87 /*
88 Notifies user about completeion of http request.
89 That's the last call from http library for given http request
90
91 Parameters:
92 http - http client object
93 callbackData - user-provided data
94 result - 'OK' for successfully completed operations
95 mike 1.1 or corresponding error code
96 */
97 typedef void (*HttpClientCallbackOnStatus)(
98 HttpClient* http,
99 void* callbackData,
100 MI_Result result);
101
102 /*
103 Notifies user about response from server.
104 First time it provides repsonse headers
105 and may provide intial part of repsonse content.
106 It may be called several more times to deliver the rest of the content.
107
108 Parameters:
109 http - http client object
110 callbackData - user-provided data
111 headers - [opt] http headers from repsonse.
112 this parameter is only provided with first call
113 and will be null with any additional calls
114 contentSize - total size of the payload.
115 '0' if no payload (empty response)
116 mike 1.1 'negative' if payload size is unknown (chunked encoding)
117 lastChunk - indication of current chunk is the last one and entire
118 content was downloaded. Useful for chunked encoding.
119 data - [opt] content to send. if message is accepted to be sent,
120 on return *data == null (taking memory ownership)
121
122 Returns:
123 'TRUE' if operation should continue;
124 'FALSE' to abort operation and close socket connection.
125 */
126 typedef MI_Boolean (*HttpClientCallbackOnResponse)(
127 HttpClient* http,
128 void* callbackData,
129 const HttpClientResponseHeader* headers,
130 MI_Sint64 contentSize,
131 MI_Boolean lastChunk,
132 Page** data);
133
134 /*
135 Creates new http client.
136
137 mike 1.1 Parameters:
138 selfOut - [out] newly created http object (or null if failed).
139 selector - [opt] selector to use for socket monitoring. If selector not specified,
140 private one is created.
141 host - host address
142 port - port number
143 secure - flag that indicates if http or https conneciton is required
144
145 Returns:
146 'OK' on success or error code otherwise
147 */
148 MI_Result HttpClient_New_Connector(
149 HttpClient** selfOut,
150 Selector* selector, /*optional, maybe NULL*/
151 const char* host,
152 unsigned short port,
153 MI_Boolean secure,
154 HttpClientCallbackOnStatus statusCallback,
155 HttpClientCallbackOnResponse responseCallback,
|
160 mike 1.1
161 /*
162 Deletes http object, disconnects form the server
163 and frees all related resources.
164
165 Parameters:
166 self - http object
167
168 Returns:
169 OK
170 */
171 MI_Result HttpClient_Delete(
172 HttpClient* self);
173
174
175 /*
176 Sends http request.
177
178 Parameters:
179 self - http object
180 verb - [opt] "GET", "POST" or "PUT". Default is "POST"
181 mike 1.1 uri - request's URI
182 headers - [opt] extra headers for request.
183 data - [opt] content to send. if message is accepted to be sent,
184 on return *data == null (taking memory ownership)
185
186 Returns:
187 OK or appropriate error
188 */
189 MI_Result HttpClient_StartRequest(
190 HttpClient* self,
191 const char* verb,
192 const char* uri,
193 const HttpClientRequestHeaders* headers,
194 Page** data);
195
196 /*
197 Sets timeout for http connection.
198 Defualt timeout ios 1 minute
199
200 Parameters:
201 self - http object
202 mike 1.1 timeoutUsec - timeout in usecs
203 */
204 MI_Result HttpClient_SetTimeout(
205 HttpClient* self,
206 MI_Uint64 timeoutUsec);
207
208 /*
209 Runs selector to perform
210 */
211 MI_Result HttpClient_Run(
212 HttpClient* self,
213 MI_Uint64 timeoutUsec);
214
215
216 END_EXTERNC
217
218 #endif /* _omi_http_httpclient_h */
|