1
/* ***** BEGIN LICENSE BLOCK *****
2
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
4
* The contents of this file are subject to the Mozilla Public License Version
5
* 1.1 (the "License"); you may not use this file except in compliance with
6
* the License. You may obtain a copy of the License at
7
* http://www.mozilla.org/MPL/
9
* Software distributed under the License is distributed on an "AS IS" basis,
10
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11
* for the specific language governing rights and limitations under the
14
* The Original Code is the Netscape security libraries.
16
* The Initial Developer of the Original Code is
17
* Netscape Communications Corporation.
18
* Portions created by the Initial Developer are Copyright (C) 1994-2000
19
* the Initial Developer. All Rights Reserved.
23
* Alternatively, the contents of this file may be used under the terms of
24
* either the GNU General Public License Version 2 or later (the "GPL"), or
25
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
26
* in which case the provisions of the GPL or the LGPL are applicable instead
27
* of those above. If you wish to allow use of your version of this file only
28
* under the terms of either the GPL or the LGPL, and not to allow others to
29
* use your version of this file under the terms of the MPL, indicate your
30
* decision by deleting the provisions above and replace them with the notice
31
* and other provisions required by the GPL or the LGPL. If you do not delete
32
* the provisions above, a recipient may use your version of this file under
33
* the terms of any one of the MPL, the GPL or the LGPL.
35
* ***** END LICENSE BLOCK ***** */
38
* Public header for exported OCSP types.
40
* $Id: ocspt.h,v 1.4.28.2 2006/02/03 20:24:21 kaie%kuix.de Exp $
47
* The following are all opaque types. If someone needs to get at
48
* a field within, then we need to fix the API. Try very hard not
49
* make the type available to them.
51
typedef struct CERTOCSPRequestStr CERTOCSPRequest;
52
typedef struct CERTOCSPResponseStr CERTOCSPResponse;
55
* XXX I think only those first two above should need to be exported,
56
* but until I know for certain I am leaving the rest of these here, too.
58
typedef struct CERTOCSPCertIDStr CERTOCSPCertID;
59
typedef struct CERTOCSPCertStatusStr CERTOCSPCertStatus;
60
typedef struct CERTOCSPSingleResponseStr CERTOCSPSingleResponse;
63
* This interface is described in terms of an HttpClient which
64
* supports at least a specified set of functions. (An implementer may
65
* provide HttpClients with additional functionality accessible only to
66
* users with a particular implementation in mind.) The basic behavior
67
* is provided by defining a set of functions, listed in an
68
* SEC_HttpServerFcnStruct. If the implementor of a SpecificHttpClient
69
* registers his SpecificHttpClient as the default HttpClient, then his
70
* functions will be called by the user of an HttpClient, such as an
73
* The implementer of a specific HttpClient (e.g., the NSS-provided
74
* DefaultHttpClient), populates an SEC_HttpClientFcnStruct, uses it to
75
* register his client, and waits for his functions to be called.
77
* For future expandability, the SEC_HttpClientFcnStruct is defined as a
78
* union, with the version field acting as a selector. The proposed
79
* initial version of the structure is given following the definition
80
* of the union. The HttpClientState structure is implementation-
81
* dependent, and should be opaque to the user.
84
typedef void * SEC_HTTP_SERVER_SESSION;
85
typedef void * SEC_HTTP_REQUEST_SESSION;
88
* This function creates a SEC_HTTP_SERVER_SESSION object. The implementer of a
89
* specific HttpClient will allocate the necessary space, when this
90
* function is called, and will free it when the corresponding FreeFcn
91
* is called. The SEC_HTTP_SERVER_SESSION object is passed, as an opaque object,
92
* to subsequent calls.
94
* If the function returns SECSuccess, the returned SEC_HTTP_SERVER_SESSION
95
* must be cleaned up with a call to SEC_HttpServer_FreeSession,
96
* after processing is finished.
98
typedef SECStatus (*SEC_HttpServer_CreateSessionFcn)(
101
SEC_HTTP_SERVER_SESSION *pSession);
104
* This function is called to allow the implementation to attempt to keep
105
* the connection alive. Depending on the underlying platform, it might
106
* immediately return SECSuccess without having performed any operations.
107
* (If a connection has not been kept alive, a subsequent call to
108
* SEC_HttpRequest_TrySendAndReceiveFcn should reopen the connection
111
* If the connection uses nonblocking I/O, this function may return
112
* SECWouldBlock and store a nonzero value at "pPollDesc". In that case
113
* the caller may wait on the poll descriptor, and should call this function
114
* again until SECSuccess (and a zero value at "pPollDesc") is obtained.
116
typedef SECStatus (*SEC_HttpServer_KeepAliveSessionFcn)(
117
SEC_HTTP_SERVER_SESSION session,
118
PRPollDesc **pPollDesc);
121
* This function frees the client SEC_HTTP_SERVER_SESSION object, closes all
122
* SEC_HTTP_REQUEST_SESSIONs created for that server, discards all partial results,
123
* frees any memory that was allocated by the client, and invalidates any
124
* response pointers that might have been returned by prior server or request
127
typedef SECStatus (*SEC_HttpServer_FreeSessionFcn)(
128
SEC_HTTP_SERVER_SESSION session);
131
* This function creates a SEC_HTTP_REQUEST_SESSION object. The implementer of a
132
* specific HttpClient will allocate the necessary space, when this
133
* function is called, and will free it when the corresponding FreeFcn
134
* is called. The SEC_HTTP_REQUEST_SESSION object is passed, as an opaque object,
135
* to subsequent calls.
137
* An implementation that does not support the requested protocol variant
138
* (usually "http", but could eventually allow "https") or request method
139
* should return SECFailure.
141
* Timeout values may include the constants PR_INTERVAL_NO_TIMEOUT (wait
142
* forever) or PR_INTERVAL_NO_WAIT (nonblocking I/O).
144
* If the function returns SECSuccess, the returned SEC_HTTP_REQUEST_SESSION
145
* must be cleaned up with a call to SEC_HttpRequest_FreeSession,
146
* after processing is finished.
148
typedef SECStatus (*SEC_HttpRequest_CreateFcn)(
149
SEC_HTTP_SERVER_SESSION session,
150
const char *http_protocol_variant, /* usually "http" */
151
const char *path_and_query_string,
152
const char *http_request_method,
153
const PRIntervalTime timeout,
154
SEC_HTTP_REQUEST_SESSION *pRequest);
157
* This function sets data to be sent to the server for an HTTP request
158
* of http_request_method == POST. If a particular implementation
159
* supports it, the details for the POST request can be set by calling
160
* this function, prior to activating the request with TrySendAndReceiveFcn.
162
* An implementation that does not support the POST method should
163
* implement a SetPostDataFcn function that returns immediately.
165
* Setting http_content_type is optional, the parameter may
166
* by NULL or the empty string.
168
typedef SECStatus (*SEC_HttpRequest_SetPostDataFcn)(
169
SEC_HTTP_REQUEST_SESSION request,
170
const char *http_data,
171
const PRUint32 http_data_len,
172
const char *http_content_type);
175
* This function sets an additional HTTP protocol request header.
176
* If a particular implementation supports it, one or multiple headers
177
* can be added to the request by calling this function once or multiple
178
* times, prior to activating the request with TryFcn.
180
* An implementation that does not support setting additional headers
181
* should implement an AddRequestHeaderFcn function that returns immediately.
183
typedef SECStatus (*SEC_HttpRequest_AddHeaderFcn)(
184
SEC_HTTP_REQUEST_SESSION request,
185
const char *http_header_name,
186
const char *http_header_value);
189
* This function initiates or continues an HTTP request. After
190
* parameters have been set with the Create function and, optionally,
191
* modified or enhanced with the AddParams function, this call creates
192
* the socket connection and initiates the communication.
194
* If a timeout value of zero is specified, indicating non-blocking
195
* I/O, the client creates a non-blocking socket, and returns a status
196
* of SECWouldBlock and a non-NULL PRPollDesc if the operation is not
197
* complete. In that case all other return parameters are undefined.
198
* The caller is expected to repeat the call, possibly after using
199
* PRPoll to determine that a completion has occurred, until a return
200
* value of SECSuccess (and a NULL value for pPollDesc) or a return
201
* value of SECFailure (indicating failure on the network level)
204
* http_response_data_len is both input and output parameter.
205
* If a pointer to a PRUint32 is supplied, the http client is
206
* expected to check the given integer value and always set an out
207
* value, even on failure.
208
* An input value of zero means, the caller will accept any response len.
209
* A different input value indicates the maximum response value acceptable
211
* If data is successfully read and the size is acceptable to the caller,
212
* the function will return SECSuccess and set http_response_data_len to
213
* the size of the block returned in http_response_data.
214
* If the data read from the http server is larger than the acceptable
215
* size, the function will return SECFailure.
216
* http_response_data_len will be set to a value different from zero to
217
* indicate the reason of the failure.
218
* An out value of "0" means, the failure was unrelated to the
220
* An out value of "1" means, the result data is larger than the
221
* accpeptable size, but the real size is not yet known to the http client
222
* implementation and it stopped retrieving it,
223
* Any other out value combined with a return value of SECFailure
224
* will indicate the actual size of the server data.
226
* The caller is permitted to provide NULL values for any of the
227
* http_response arguments, indicating the caller is not interested in
228
* those values. If the caller does provide an address, the HttpClient
229
* stores at that address a pointer to the corresponding argument, at
230
* the completion of the operation.
232
* All returned pointers will be owned by the the HttpClient
233
* implementation and will remain valid until the call to
234
* SEC_HttpRequest_FreeFcn.
236
typedef SECStatus (*SEC_HttpRequest_TrySendAndReceiveFcn)(
237
SEC_HTTP_REQUEST_SESSION request,
238
PRPollDesc **pPollDesc,
239
PRUint16 *http_response_code,
240
const char **http_response_content_type,
241
const char **http_response_headers,
242
const char **http_response_data,
243
PRUint32 *http_response_data_len);
246
* Calling CancelFcn asks for premature termination of the request.
248
* Future calls to SEC_HttpRequest_TrySendAndReceive should
249
* by avoided, but in this case the HttpClient implementation
250
* is expected to return immediately with SECFailure.
252
* After calling CancelFcn, a separate call to SEC_HttpRequest_FreeFcn
253
* is still necessary to free resources.
255
typedef SECStatus (*SEC_HttpRequest_CancelFcn)(
256
SEC_HTTP_REQUEST_SESSION request);
259
* Before calling this function, it must be assured the request
260
* has been completed, i.e. either SEC_HttpRequest_TrySendAndReceiveFcn has
261
* returned SECSuccess, or the request has been canceled with
262
* a call to SEC_HttpRequest_CancelFcn.
264
* This function frees the client state object, closes all sockets,
265
* discards all partial results, frees any memory that was allocated
266
* by the client, and invalidates all response pointers that might
267
* have been returned by SEC_HttpRequest_TrySendAndReceiveFcn
269
typedef SECStatus (*SEC_HttpRequest_FreeFcn)(
270
SEC_HTTP_REQUEST_SESSION request);
272
typedef struct SEC_HttpClientFcnV1Struct {
273
SEC_HttpServer_CreateSessionFcn createSessionFcn;
274
SEC_HttpServer_KeepAliveSessionFcn keepAliveSessionFcn;
275
SEC_HttpServer_FreeSessionFcn freeSessionFcn;
276
SEC_HttpRequest_CreateFcn createFcn;
277
SEC_HttpRequest_SetPostDataFcn setPostDataFcn;
278
SEC_HttpRequest_AddHeaderFcn addHeaderFcn;
279
SEC_HttpRequest_TrySendAndReceiveFcn trySendAndReceiveFcn;
280
SEC_HttpRequest_CancelFcn cancelFcn;
281
SEC_HttpRequest_FreeFcn freeFcn;
282
} SEC_HttpClientFcnV1;
284
typedef struct SEC_HttpClientFcnStruct {
287
SEC_HttpClientFcnV1 ftable1;
288
/* SEC_HttpClientFcnV2 ftable2; */
293
#endif /* _OCSPT_H_ */