|
NCBI Home IEB Home C Toolkit docs C++ Toolkit source browser C Toolkit source browser (2) |
NCBI C Toolkit Cross ReferenceC/connect/ncbi_connutil.h |
source navigation diff markup identifier search freetext search file search |
1 #ifndef CONNECT___NCBI_CONNUTIL__H
2 #define CONNECT___NCBI_CONNUTIL__H
3
4 /* $Id: ncbi_connutil.h,v 6.69 2009/10/30 14:39:33 kazimird Exp $
5 * ===========================================================================
6 *
7 * PUBLIC DOMAIN NOTICE
8 * National Center for Biotechnology Information
9 *
10 * This software/database is a "United States Government Work" under the
11 * terms of the United States Copyright Act. It was written as part of
12 * the author's official duties as a United States Government employee and
13 * thus cannot be copyrighted. This software/database is freely available
14 * to the public for use. The National Library of Medicine and the U.S.
15 * Government have not placed any restriction on its use or reproduction.
16 *
17 * Although all reasonable efforts have been taken to ensure the accuracy
18 * and reliability of the software and data, the NLM and the U.S.
19 * Government do not and cannot warrant the performance or results that
20 * may be obtained by using this software or data. The NLM and the U.S.
21 * Government disclaim all warranties, express or implied, including
22 * warranties of performance, merchantability or fitness for any particular
23 * purpose.
24 *
25 * Please cite the author in any work or product based on this material.
26 *
27 * ===========================================================================
28 *
29 * Author: Denis Vakatov, Anton Lavrentiev
30 *
31 * File Description:
32 * Auxiliary API to:
33 * 1.Retrieve connection related info from the registry:
34 * SConnNetInfo
35 * ConnNetInfo_Create()
36 * ConnNetInfo_AdjustForHttpProxy()
37 * ConnNetInfo_Clone()
38 * ConnNetInfo_Print()
39 * ConnNetInfo_Destroy()
40 * ConnNetInfo_Log()
41 * ConnNetInfo_ParseURL()
42 * ConnNetInfo_SetUserHeader()
43 * ConnNetInfo_AppendUserHeader()
44 * ConnNetInfo_DeleteUserHeader()
45 * ConnNetInfo_OverrideUserHeader()
46 * ConnNetInfo_ExtendUserHeader()
47 * ConnNetInfo_AppendArg()
48 * ConnNetInfo_PrependArg()
49 * ConnNetInfo_DeleteArg()
50 * ConnNetInfo_DeleteAllArgs()
51 * ConnNetInfo_PreOverrideArg()
52 * ConnNetInfo_PostOverrideArg()
53 * ConnNetInfo_SetupStandardArgs()
54 * #define REG_CONN_***
55 * #define DEF_CONN_***
56 *
57 * 2.Make a connection to an URL:
58 * URL_Connect[Ex]()
59 *
60 * 3.Perform URL encoding/decoding of data:
61 * URL_Encode()
62 * URL_Decode[Ex]()
63 *
64 * 5.Compose or parse NCBI-specific Content-Type's:
65 * EMIME_Type
66 * EMIME_SubType
67 * EMIME_Encoding
68 * MIME_ComposeContentType()
69 * MIME_ParseContentType()
70 *
71 * 6.Search for a token in the input stream (either CONN or SOCK):
72 * CONN_StripToPattern()
73 * SOCK_StripToPattern()
74 * BUF_StripToPattern()
75 *
76 */
77
78 #include <connect/ncbi_buffer.h>
79 #include <connect/ncbi_connection.h>
80 #include <connect/ncbi_socket.h>
81
82
83 /** @addtogroup UtilityFunc
84 *
85 * @{
86 */
87
88
89 #ifdef __cplusplus
90 extern "C" {
91 #endif
92
93
94 typedef enum {
95 eURL_Unspec = 0,
96 eURL_Https,
97 eURL_Http,
98 eURL_File,
99 eURL_Ftp
100 } EURLScheme;
101
102
103 typedef enum {
104 eReqMethod_Any = 0,
105 eReqMethod_Post,
106 eReqMethod_Get
107 } EReqMethod;
108
109
110 typedef enum {
111 eDebugPrintout_None = 0,
112 eDebugPrintout_Some,
113 eDebugPrintout_Data
114 } EDebugPrintout;
115
116
117 /* Network connection related configurable info struct.
118 * ATTENTION: Do NOT fill out this structure (SConnNetInfo) "from scratch"!
119 * Instead, use ConnNetInfo_Create() described below to create
120 * it, and then fix (hard-code) some fields, if really necessary.
121 * NOTE: Not all fields are fully user throughout the library.
122 */
123 typedef struct {
124 char client_host[256]; /* effective client hostname ('\0'=def) */
125 EURLScheme scheme; /* only pre-defined types (limited) */
126 char user[128]; /* username (if specified) */
127 char pass[128]; /* password (if any, clear text!!!) */
128 char host[256]; /* host to connect to */
129 unsigned short port; /* port to connect to, host byte order */
130 char path[1024]; /* service: path(e.g. to a CGI script) */
131 char args[1024]; /* service: args(e.g. for a CGI script) */
132 EReqMethod req_method; /* method to use in the request (HTTP) */
133 STimeout* timeout; /* ptr to i/o tmo (infinite if NULL) */
134 unsigned short max_try; /* max. # of attempts to connect (>= 1) */
135 char http_proxy_host[256]; /* hostname of HTTP proxy server */
136 unsigned short http_proxy_port; /* port # of HTTP proxy server */
137 char proxy_host[256]; /* CERN-like (non-transp) f/w proxy srv */
138 EDebugPrintout debug_printout; /* printout some debug info */
139 int/*bool*/ stateless; /* to connect in HTTP-like fashion only */
140 int/*bool*/ firewall; /* to use firewall/relay in connects */
141 int/*bool*/ lb_disable; /* to disable local load-balancing */
142 const char* http_user_header; /* user header to add to HTTP request */
143 const char* http_referer; /* default referrer (when not spec'd) */
144
145 /* the following field(s) are for the internal use only -- don't touch! */
146 int/*bool*/ http_proxy_adjusted;
147 STimeout tmo; /* default storage for finite timeout */
148 const char* service; /* service for which this info created */
149 } SConnNetInfo;
150
151
152 /* Defaults and the registry entry names for "SConnNetInfo" fields
153 */
154 #define DEF_CONN_REG_SECTION "CONN"
155
156 #define REG_CONN_SCHEME "SCHEME"
157 #define DEF_CONN_SCHEME 0
158
159 #define REG_CONN_USER "USER"
160 #define DEF_CONN_USER ""
161
162 #define REG_CONN_PASS "PASS"
163 #define DEF_CONN_PASS ""
164
165 #define REG_CONN_HOST "HOST"
166 #define DEF_CONN_HOST "www.ncbi.nlm.nih.gov"
167
168 #define REG_CONN_PORT "PORT"
169 #define DEF_CONN_PORT 0
170
171 #define REG_CONN_PATH "PATH"
172 #define DEF_CONN_PATH "/Service/dispd.cgi"
173
174 #define REG_CONN_ARGS "ARGS"
175 #define DEF_CONN_ARGS ""
176
177 #define REG_CONN_REQ_METHOD "REQ_METHOD"
178 #define DEF_CONN_REQ_METHOD "ANY"
179
180 #define REG_CONN_TIMEOUT "TIMEOUT"
181 #define DEF_CONN_TIMEOUT 30.0
182
183 #define REG_CONN_MAX_TRY "MAX_TRY"
184 #define DEF_CONN_MAX_TRY 3
185
186 #define REG_CONN_HTTP_PROXY_HOST "HTTP_PROXY_HOST"
187 #define DEF_CONN_HTTP_PROXY_HOST ""
188
189 #define REG_CONN_HTTP_PROXY_PORT "HTTP_PROXY_PORT"
190 #define DEF_CONN_HTTP_PROXY_PORT ""
191
192 #define REG_CONN_PROXY_HOST "PROXY_HOST"
193 #define DEF_CONN_PROXY_HOST ""
194
195 #define REG_CONN_DEBUG_PRINTOUT "DEBUG_PRINTOUT"
196 #define DEF_CONN_DEBUG_PRINTOUT ""
197
198 #define REG_CONN_STATELESS "STATELESS"
199 #define DEF_CONN_STATELESS ""
200
201 #define REG_CONN_FIREWALL "FIREWALL"
202 #define DEF_CONN_FIREWALL ""
203
204 #define REG_CONN_LB_DISABLE "LB_DISABLE"
205 #define DEF_CONN_LB_DISABLE ""
206
207 #define REG_CONN_HTTP_USER_HEADER "HTTP_USER_HEADER"
208 #define DEF_CONN_HTTP_USER_HEADER ""
209
210 #define REG_CONN_HTTP_REFERER "HTTP_REFERER"
211 #define DEF_CONN_HTTP_REFERER 0
212
213 /* Environment/registry keys that are *not* kept in SConnNetInfo */
214 #define REG_CONN_SERVICE_NAME "SERVICE_NAME"
215 #define REG_CONN_LOCAL_ENABLE "LOCAL_ENABLE"
216 #define REG_CONN_LBSMD_DISABLE "LBSMD_DISABLE"
217 #define REG_CONN_DISPD_DISABLE "DISPD_DISABLE"
218
219 /* Local service dispatcher */
220 #define REG_CONN_LOCAL_SERVICES "LOCAL_SERVICES"
221 #define REG_CONN_LOCAL_SERVER DEF_CONN_REG_SECTION "_LOCAL_SERVER"
222
223
224 extern NCBI_XCONNECT_EXPORT const char* ConnNetInfo_GetValue
225 (const char* service,
226 const char* param,
227 char* value,
228 size_t value_size,
229 const char* def_value
230 );
231
232
233 /* This function to fill out the "*info" structure using
234 * registry entries named (see above) in macros REG_CONN_<NAME>:
235 *
236 * -- INFO FIELD -- ----- NAME ----- ---------- REMARKS/EXAMPLES ---------
237 * client_host local host name assigned automatically
238 * service_name SERVICE_NAME no search/no value without service
239 * host HOST
240 * port PORT
241 * path PATH
242 * args ARGS
243 * req_method REQ_METHOD
244 * timeout TIMEOUT "<sec>.<usec>": "3.00005", "infinite"
245 * max_try MAX_TRY
246 * http_proxy_host HTTP_PROXY_HOST no HTTP proxy if empty/NULL
247 * http_proxy_port HTTP_PROXY_PORT
248 * proxy_host PROXY_HOST
249 * debug_printout DEBUG_PRINTOUT
250 * stateless STATELESS
251 * firewall FIREWALL
252 * lb_disable LB_DISABLE
253 * http_user_header HTTP_USER_HEADER "\r\n" if missing is appended
254 * http_referer HTTP_REFERER may be assigned automatically
255 *
256 * A value of the field NAME is first looked up in the environment variable
257 * of the form service_CONN_<NAME>; then in the current corelib registry,
258 * in the section 'service' by using key CONN_<NAME>; then in the environment
259 * variable again, but using the name CONN_<NAME>; and finally in the default
260 * registry section (DEF_CONN_REG_SECTION), using just <NAME>. If service
261 * is NULL or empty then the first 2 steps in the above lookup are skipped.
262 *
263 * For default values see right above, in macros DEF_CONN_<NAME>.
264 */
265 extern NCBI_XCONNECT_EXPORT SConnNetInfo* ConnNetInfo_Create
266 (const char* service
267 );
268
269
270 /* Adjust the "host:port" to "proxy_host:proxy_port", and
271 * "path" to "http://host:port/path" to connect through an HTTP proxy.
272 * Return FALSE if cannot adjust (e.g. if "host" + "path" are too long).
273 * NOTE: it does nothing if applied more than once to the same "info"
274 * (or its clone), or when "http_proxy_host" is empty, but
275 * returns TRUE.
276 */
277 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_AdjustForHttpProxy
278 (SConnNetInfo* info
279 );
280
281
282 /* Make an exact and independent copy of "*info".
283 */
284 extern NCBI_XCONNECT_EXPORT SConnNetInfo* ConnNetInfo_Clone
285 (const SConnNetInfo* info
286 );
287
288
289 /* Convenience routines to manipulate SConnNetInfo::args[].
290 * In "arg" all routines below assume to have a single arg name
291 * or an "arg=value" pair. In the former case, additional "val"
292 * may be supplied separately (and will be prepended by "=" if
293 * necessary). In the latter case, having a non-zero string in
294 * "val" may result in an erroneous behavior. Ampersand (&) gets
295 * automatically added to keep the arg list correct.
296 * Return value (if any): none-zero on success; 0 on error.
297 */
298
299 /* append argument to the end of the list */
300 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_AppendArg
301 (SConnNetInfo* info,
302 const char* arg,
303 const char* val
304 );
305
306 /* put argument in the front of the list */
307 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_PrependArg
308 (SConnNetInfo* info,
309 const char* arg,
310 const char* val
311 );
312
313 /* delete one (first) argument from the list of arguments in "info" */
314 extern NCBI_XCONNECT_EXPORT void ConnNetInfo_DeleteArg
315 (SConnNetInfo* info,
316 const char* arg
317 );
318
319 /* delete all arguments specified in "args" from the list in "info" */
320 extern NCBI_XCONNECT_EXPORT void ConnNetInfo_DeleteAllArgs
321 (SConnNetInfo* info,
322 const char* args
323 );
324
325 /* same as sequence DeleteAll(arg) then Prepend(arg, val), see above */
326 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_PreOverrideArg
327 (SConnNetInfo* info,
328 const char* arg,
329 const char* val
330 );
331
332 /* same as sequence DeleteAll(arg) then Append(arg, val), see above */
333 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_PostOverrideArg
334 (SConnNetInfo* info,
335 const char* arg,
336 const char* val
337 );
338
339
340 /* Set user header (discard previously set header, if any).
341 * Reset the old header (if any) if "header" == NULL.
342 * Return non-zero if successful, otherwise return 0 to indicate an error.
343 */
344 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_SetUserHeader
345 (SConnNetInfo* info,
346 const char* header
347 );
348
349
350 /* Append user header (same as ConnNetInfo_SetUserHeader() if no previous
351 * header was set); do nothing if the provided "header" is NULL or empty.
352 * Return non-zero if successful, otherwise return 0 to indicate an error.
353 */
354 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_AppendUserHeader
355 (SConnNetInfo* info,
356 const char* header
357 );
358
359
360 /* Override user header.
361 * Tags replaced (case-insensitively), and tags with empty values effectively
362 * delete existing tags from the old user header, e.g. "My-Tag:\r\n" deletes
363 * a first appearence (if any) of "My-Tag: [<value>]" from the user header.
364 * Unmatched tags with non-empty values are simply added to the existing user
365 * header (as with "Append" above).
366 * Return non-zero if successful, otherwise return 0 to indicate an error.
367 */
368 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_OverrideUserHeader
369 (SConnNetInfo* info,
370 const char* header
371 );
372
373
374 /* Extend user header.
375 * Existings tags matching (case-insensitively) first appearances of those
376 * from "header" get appended with new value (separated by a space) if the
377 * added value is non-empty, otherwise, the tags are left untouched. If new
378 * tag value matches (case-insensitively) last tag value already in the
379 * header, the new value does not get added (to avoid repetitive duplicates).
380 * All new unmatched tags from "header" with non-empty values get added
381 * to the end of the user header (as with "Append" above).
382 * Return non-zero if successful, otherwise return 0 to indicate an error.
383 */
384 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_ExtendUserHeader
385 (SConnNetInfo* info,
386 const char* header
387 );
388
389
390 /* Delete entries from current user header, if their tags match those
391 * passed in "hdr" (regardless of the values, if any, in the latter).
392 */
393 extern NCBI_XCONNECT_EXPORT void ConnNetInfo_DeleteUserHeader
394 (SConnNetInfo* info,
395 const char* hdr
396 );
397
398
399 /* Parse URL into "*info", using (service-specific, if any) defaults.
400 */
401 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_ParseURL
402 (SConnNetInfo* info,
403 const char* url
404 );
405
406
407 /* Setup standard arguments: service(as passed), address, and platform.
408 * Return non-zero on success; zero on error.
409 */
410 extern NCBI_XCONNECT_EXPORT int/*bool*/ ConnNetInfo_SetupStandardArgs
411 (SConnNetInfo* info,
412 const char* service
413 );
414
415
416 /* Log the contents of "*info".
417 */
418 extern NCBI_XCONNECT_EXPORT void ConnNetInfo_Log
419 (const SConnNetInfo* info,
420 LOG log
421 );
422
423
424 /* Reconstruct text URL out of SConnNetInfo components
425 * (username:password excluded for security reasons).
426 * Returned string must be free()'d when no longer necessary.
427 * Return NULL on error.
428 */
429 extern NCBI_XCONNECT_EXPORT char* ConnNetInfo_URL
430 (const SConnNetInfo* info
431 );
432
433
434 /* Destroy and deallocate "info" (if not NULL).
435 */
436 extern NCBI_XCONNECT_EXPORT void ConnNetInfo_Destroy(SConnNetInfo* info);
437
438
439
440 /* Hit URL "http[s]://host[:port]/path?args" with the following
441 * request (argument substitution enclosed in angle brackets, with
442 * optional parts in square brackets):
443 *
444 * {POST|GET} <path>[?<args>] HTTP/1.0\r\n
445 * Host: <host>[:port]
446 * [<user_header>]
447 * Content-Length: <content_length>\r\n
448 *
449 * Request method eReqMethod_Any selects appropriate method depending on
450 * the passed value of "content_length": GET when no content is expected
451 * (content_length==0), and POST when "content_length" provided non-zero.
452 *
453 * If "port" is not specified (0) it will be assigned automatically
454 * to a well-known value depending on the setting of fSOCK_Secure in
455 * the passed "flags" parameter.
456 *
457 * The "content_length" is mandatory, and it specifies an exact(!) amount of
458 * data that you are planning to send to the resultant socket (0 if none).
459 *
460 * If string "user_header" is not NULL/empty, then it *must* be terminated
461 * by a single '\r\n'.
462 *
463 * If "encode_args" is TRUE then URL-encode the "args".
464 * "args" can be NULL/empty -- then the '?' symbol does not get added.
465 *
466 * On success, return eIO_Success and non-NULL handle of a socket via last
467 * parameter.
468 * ATTENTION: due to the very essence of the HTTP connection, you may
469 * perform only one { WRITE, ..., WRITE, READ, ..., READ } cycle.
470 * Returned socket must be closed exipicitly by "ncbi_socket.h:SOCK_Close()"
471 * when no longer needed.
472 * On error, return specific code (last parameter may not be updated),
473 * no socket gets created.
474 *
475 * NOTE: Returned socket may not be immediately readable/writeable if open
476 * and/or read/write timeouts were passed as {0,0}, meaning that both
477 * connection and HTTP header write operation may still be pending in
478 * the resultant socket. It is responsibility of the application to
479 * analyze the actual socket state in this case (see "ncbi_socket.h").
480 */
481
482 extern NCBI_XCONNECT_EXPORT EIO_Status URL_ConnectEx
483 (const char* host, /* must be provided */
484 unsigned short port, /* may be 0, defaulted to either 80 or 443 */
485 const char* path, /* must be provided */
486 const char* args, /* may be NULL or empty */
487 EReqMethod req_method, /* ANY selects method by "content_length" */
488 size_t content_length,
489 const STimeout* c_timeout, /* timeout for the CONNECT stage */
490 const STimeout* rw_timeout, /* timeout for READ and WRITE */
491 const char* user_header,
492 int/*bool*/ encode_args, /* URL-encode the "args", if any */
493 TSOCK_Flags flags, /* additional socket requirements */
494 SOCK* sock /* returned socket (on eIO_Success only) */
495 );
496
497 /* Equivalent to the above except that it returns non-NULL socket handle
498 * on success, and NULL on error without providing a reason for the failure. */
499 extern NCBI_XCONNECT_EXPORT SOCK URL_Connect
500 (const char* host, /* must be provided */
501 unsigned short port, /* may be 0, defaulted to either 80 or 443 */
502 const char* path, /* must be provided */
503 const char* args, /* may be NULL or empty */
504 EReqMethod req_method, /* ANY selects method by "content_length" */
505 size_t content_length,
506 const STimeout* c_timeout, /* timeout for the CONNECT stage */
507 const STimeout* rw_timeout, /* timeout for READ and WRITE */
508 const char* user_header,
509 int/*bool*/ encode_args, /* URL-encode the "args", if any */
510 TSOCK_Flags flags /* additional socket requirements */
511 );
512
513
514 /* Discard all input data before(and including) the first occurrence of
515 * "pattern". If "buf" is not NULL then add the discarded data(including
516 * the "pattern") to it. If "n_discarded" is not NULL then "*n_discarded"
517 * will return # of discarded bytes.
518 * NOTE: "pattern" == NULL causes stripping to the EOF.
519 */
520 extern NCBI_XCONNECT_EXPORT EIO_Status CONN_StripToPattern
521 (CONN conn,
522 const void* pattern,
523 size_t pattern_size,
524 BUF* buf,
525 size_t* n_discarded
526 );
527
528 extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_StripToPattern
529 (SOCK sock,
530 const void* pattern,
531 size_t pattern_size,
532 BUF* buf,
533 size_t* n_discarded
534 );
535
536 extern NCBI_XCONNECT_EXPORT EIO_Status BUF_StripToPattern
537 (BUF buffer,
538 const void* pattern,
539 size_t pattern_size,
540 BUF* buf,
541 size_t* n_discarded
542 );
543
544
545
546 /* URL-encode up to "src_size" symbols(bytes) from buffer "src_buf".
547 * Write the encoded data to buffer "dst_buf", but no more than "dst_size"
548 * bytes.
549 * Assign "*src_read" to the # of bytes successfully encoded from "src_buf".
550 * Assign "*dst_written" to the # of bytes written to buffer "dst_buf".
551 */
552 extern NCBI_XCONNECT_EXPORT void URL_Encode
553 (const void* src_buf, /* [in] non-NULL */
554 size_t src_size, /* [in] */
555 size_t* src_read, /* [out] non-NULL */
556 void* dst_buf, /* [in/out] non-NULL */
557 size_t dst_size, /* [in] */
558 size_t* dst_written /* [out] non-NULL */
559 );
560
561
562 /* URL-decode up to "src_size" symbols(bytes) from buffer "src_buf".
563 * Write the decoded data to buffer "dst_buf", but no more than "dst_size"
564 * bytes.
565 * Assign "*src_read" to the # of bytes successfully decoded from "src_buf".
566 * Assign "*dst_written" to the # of bytes written to buffer "dst_buf".
567 * Return FALSE (0) only if cannot decode anything, and an unrecoverable
568 * URL-encoding error (such as an invalid symbol or a bad "%.." sequence)
569 * has occurred.
570 * NOTE: the unfinished "%.." sequence is fine -- return TRUE, but dont
571 * "read" it.
572 */
573 extern NCBI_XCONNECT_EXPORT int/*bool*/ URL_Decode
574 (const void* src_buf, /* [in] non-NULL */
575 size_t src_size, /* [in] */
576 size_t* src_read, /* [out] non-NULL */
577 void* dst_buf, /* [in/out] non-NULL */
578 size_t dst_size, /* [in] */
579 size_t* dst_written /* [out] non-NULL */
580 );
581
582
583 /* Act just like URL_Decode (see above) but caller can allow the specified
584 * non-standard URL symbols in the input buffer to be decoded "as is".
585 * The extra allowed symbols are passed in a '\0'-terminated string
586 * "allow_symbols" (it can be NULL or empty -- then this will be an exact
587 * equivalent of URL_Decode).
588 */
589 extern NCBI_XCONNECT_EXPORT int/*bool*/ URL_DecodeEx
590 (const void* src_buf, /* [in] non-NULL */
591 size_t src_size, /* [in] */
592 size_t* src_read, /* [out] non-NULL */
593 void* dst_buf, /* [in/out] non-NULL */
594 size_t dst_size, /* [in] */
595 size_t* dst_written, /* [out] non-NULL */
596 const char* allow_symbols /* [in] '\0'-term */
597 );
598
599
600
601 /****************************************************************************
602 * NCBI-specific MIME content type and sub-types
603 * (the API to compose and parse them)
604 * Content-Type: <type>/<MIME_ComposeSubType()>\r\n
605 *
606 * Content-Type: <type>/<subtype>-<encoding>\r\n
607 *
608 * where MIME_ComposeSubType(EMIME_SubType subtype, EMIME_Encoding encoding):
609 * "x-<subtype>-<encoding>":
610 * "x-<subtype>", "x-<subtype>-urlencoded", "x-<subtype>-<encoding>",
611 * "x-dispatch", "x-dispatch-urlencoded", "x-dispatch-<encoding>
612 * "x-asn-text", "x-asn-text-urlencoded", "x-asn-text-<encoding>
613 * "x-asn-binary", "x-asn-binary-urlencoded", "x-asn-binary-<encoding>"
614 * "x-www-form", "x-www-form-urlencoded", "x-www-form-<encoding>"
615 * "html", "html-urlencoded", "html-<encoding>"
616 * "x-unknown", "x-unknown-urlencoded", "x-unknown-<encoding>"
617 *
618 * Note: <subtype> and <encoding> are expected to contain only
619 * alphanumeric symbols, '-' and '_'. They are case-insensitive.
620 ****************************************************************************/
621
622
623 /* Type
624 */
625 typedef enum {
626 eMIME_T_Undefined = -1,
627 eMIME_T_NcbiData = 0, /* "x-ncbi-data" (NCBI specific data) */
628 eMIME_T_Text, /* "text" */
629 eMIME_T_Application, /* "application" */
630 /* eMIME_T_???, "<type>" here go other types */
631 eMIME_T_Unknown /* "unknown" */
632 } EMIME_Type;
633
634
635 /* SubType
636 */
637 typedef enum {
638 eMIME_Undefined = -1,
639 eMIME_Dispatch = 0, /* "x-dispatch" (dispatcher info) */
640 eMIME_AsnText, /* "x-asn-text" (text ASN.1 data) */
641 eMIME_AsnBinary, /* "x-asn-binary" (binary ASN.1 data) */
642 eMIME_Fasta, /* "x-fasta" (data in FASTA format) */
643 eMIME_WwwForm, /* "x-www-form" */
644 /* standard MIMEs */
645 eMIME_Html, /* "html" */
646 eMIME_Plain, /* "plain" */
647 eMIME_Xml, /* "xml" */
648 eMIME_XmlSoap, /* "xml+soap" */
649 eMIME_OctetStream, /* "octet-stream" */
650 /* eMIME_???, "<subtype>" here go other NCBI subtypes */
651 eMIME_Unknown /* "x-unknown" (an arbitrary binary data) */
652 } EMIME_SubType;
653
654
655 /* Encoding
656 */
657 typedef enum {
658 eENCOD_None = 0, /* "" (the content is passed "as is") */
659 eENCOD_Url, /* "-urlencoded" (the content is URL-encoded) */
660 /* eENCOD_???, "-<encoding>" here go other NCBI encodings */
661 eENCOD_Unknown /* "-encoded" (unknown encoding) */
662 } EMIME_Encoding;
663
664
665 /* Write up to "buflen" bytes to "buf":
666 * Content-Type: <type>/[x-]<subtype>-<encoding>\r\n
667 * Return pointer to the "buf".
668 */
669 #define MAX_CONTENT_TYPE_LEN 64
670 extern NCBI_XCONNECT_EXPORT char* MIME_ComposeContentTypeEx
671 (EMIME_Type type,
672 EMIME_SubType subtype,
673 EMIME_Encoding encoding,
674 char* buf,
675 size_t buflen /* must be at least MAX_CONTENT_TYPE_LEN */
676 );
677
678 /* Parse the NCBI-specific content-type; the (case-insensitive) "str"
679 * can be in the following two formats:
680 * Content-Type: <type>/x-<subtype>-<encoding>
681 * <type>/x-<subtype>-<encoding>
682 *
683 * NOTE: all leading spaces and all trailing spaces (and any trailing symbols,
684 * if they separated from the content type by at least one space) will
685 * be ignored, e.g. these are valid content type strings:
686 * " Content-Type: text/plain foobar"
687 * " text/html \r\n barfoo coocoo ....\n boooo"
688 *
689 * If it does not match any of NCBI MIME type/subtypes/encodings, then
690 * return TRUE, eMIME_T_Unknown, eMIME_Unknown or eENCOD_None, respectively.
691 * If the passed "str" has an invalid (non-HTTP ContentType) format
692 * (or if it is NULL/empty), then
693 * return FALSE, eMIME_T_Undefined, eMIME_Undefined, and eENCOD_None
694 */
695 extern NCBI_XCONNECT_EXPORT int/*bool*/ MIME_ParseContentTypeEx
696 (const char* str, /* the HTTP "Content-Type:" header to parse */
697 EMIME_Type* type, /* can be NULL */
698 EMIME_SubType* subtype, /* can be NULL */
699 EMIME_Encoding* encoding /* can be NULL */
700 );
701
702
703 #ifndef NCBI_DEPRECATED
704 # define NCBI_CONNUTIL_DEPRECATED
705 #else
706 # define NCBI_CONNUTIL_DEPRECATED NCBI_DEPRECATED
707 #endif
708
709 /* Exactly equivalent to MIME_ComposeContentTypeEx(eMIME_T_NcbiData, ...)
710 * Use more explicit Ex variant instead.
711 */
712 extern NCBI_XCONNECT_EXPORT NCBI_CONNUTIL_DEPRECATED
713 char* MIME_ComposeContentType
714 (EMIME_SubType subtype,
715 EMIME_Encoding encoding,
716 char* buf,
717 size_t buflen
718 );
719
720 /* Requires the MIME type be "x-ncbi-data".
721 * Use more explicit Ex variant instead.
722 */
723 extern NCBI_XCONNECT_EXPORT NCBI_CONNUTIL_DEPRECATED
724 int/*bool*/ MIME_ParseContentType
725 (const char* str, /* the HTTP "Content-Type:" header to parse */
726 EMIME_SubType* subtype, /* can be NULL */
727 EMIME_Encoding* encoding /* can be NULL */
728 );
729
730
731 #ifdef __cplusplus
732 } /* extern "C" */
733 #endif
734
735
736 /* @} */
737
738 #endif /* CONNECT___NCBI_CONNUTIL__H */
739 |
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more information. |