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>
31 #include <sock/selector.h>
32
33 BEGIN_EXTERNC
34
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 mike 1.1 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 {
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 mike 1.1 {
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 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 mike 1.1
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 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 mike 1.1 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 '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 mike 1.1 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 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 mike 1.1 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,
156 void* callbackData);
157
158 /*
159 Deletes http object, disconnects form the server
160 and frees all related resources.
161
162 Parameters:
163 self - http object
164
165 Returns:
166 OK
167 */
168 MI_Result HttpClient_Delete(
169 mike 1.1 HttpClient* self);
170
171
172 /*
173 Sends http request.
174
175 Parameters:
176 self - http object
177 verb - [opt] "GET", "POST" or "PUT". Default is "POST"
178 uri - request's URI
179 headers - [opt] extra headers for request.
180 data - [opt] content to send. if message is accepted to be sent,
181 on return *data == null (taking memory ownership)
182
183 Returns:
184 OK or appropriate error
185 */
186 MI_Result HttpClient_StartRequest(
187 HttpClient* self,
188 const char* verb,
189 const char* uri,
190 mike 1.1 const HttpClientRequestHeaders* headers,
191 Page** data);
192
193 /*
194 Sets timeout for http connection.
195 Defualt timeout ios 1 minute
196
197 Parameters:
198 self - http object
199 timeoutUsec - timeout in usecs
200 */
201 MI_Result HttpClient_SetTimeout(
202 HttpClient* self,
203 MI_Uint64 timeoutUsec);
204
205 /*
206 Runs selector to perform
207 */
208 MI_Result HttpClient_Run(
209 HttpClient* self,
210 MI_Uint64 timeoutUsec);
211 mike 1.1
212
213 END_EXTERNC
214
215 #endif /* _omi_http_httpclient_h */
|
Return to
httpclient.h
CVS log
Up to [OMI] / omi / http