1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
|
/* $Id: ncbiwww.h,v 6.8 2007/06/20 22:05:40 vakatov Exp $
* ===========================================================================
*
* PUBLIC DOMAIN NOTICE
* National Center for Biotechnology Information
*
* This software/database is a "United States Government Work" under the
* terms of the United States Copyright Act. It was written as part of
* the author's official duties as a United States Government employee and
* thus cannot be copyrighted. This software/database is freely available
* to the public for use. The National Library of Medicine and the U.S.
* Government have not placed any restriction on its use or reproduction.
*
* Although all reasonable efforts have been taken to ensure the accuracy
* and reliability of the software and data, the NLM and the U.S.
* Government do not and cannot warrant the performance or results that
* may be obtained by using this software or data. The NLM and the U.S.
* Government disclaim all warranties, express or implied, including
* warranties of performance, merchantability or fitness for any particular
* purpose.
*
* Please cite the author in any work or product based on this material.
*
* ===========================================================================
*
* File Name: $RCSfile: ncbiwww.h,v $
*
* Author: Sergei Shavirin
*
* Version Creation Date: 11/03/1996
*
* $Revision: 6.8 $
*
* File Description:
* This file contains main definitions to read and process HTTP
* protocols input for WWW CGI programs
* Currently it works for all ncbi supported platforms.
*
* $Log: ncbiwww.h,v $
* Revision 6.8 2007/06/20 22:05:40 vakatov
* MAX_WWW_ENTRIES -- increased from 4096 to 32768.
* It is just a quick-fix to let this code live a little longer, requested
* by Karl and Vasuki.
*
* Revision 6.7 2002/02/07 14:48:22 ivanov
* Added WWWGetEntriesEx(), WWWGetEntriesFormDataEx(), WWWReadFileInMemoryEx(),
* WWWGetValueSizeByIndex() -- support binary files in the multipart form-data.
*
* Revision 6.6 2002/01/28 21:27:00 ivanov
* Added WWWGetArgsEx() and WWWGetArgsAttr_...() functions.
* Added structure SWWWGetArgsAttr definition.
*
* Revision 6.5 2001/05/10 14:58:35 shavirin
* Fixed typo.
*
* Revision 6.4 2001/05/09 19:25:35 shavirin
* Added function WWWGetProxiedIP() to get 'real' address of the client
* using PROXIED_IP environment set by proxy server.
*
* Revision 6.3 1999/09/29 19:08:43 shavirin
* Added new functions: WWWGetLastValueByName and WWWFindNameEx
*
* Revision 6.2 1999/08/18 18:48:40 shavirin
* Increased number of MAX_WWW_ENTRIES to 4096.
*
* Revision 6.1 1999/01/26 19:43:27 vakatov
* Adopted for 32-bit MS-Windows DLLs
*
* Revision 5.1 1997/05/09 16:01:25 vakatov
* "ncbicoll.[ch]" is not being used anywhere anymore -- remove it!
* Move "ncbiwww.h" and "wwwutils.c" from /network/www2(ncbiwww2.lib)
* to /corelib(ncbi.lib)
*
* Revision 1.7 1997/04/04 21:26:32 savchuk
* WWWInfoPtr definition has been changed.
* WWWInfoNew() prototype has been removed
*
* Revision 1.6 1997/02/26 15:20:50 shavirin
* Added definition of function WWWGetDocRoot()
*
* Revision 1.5 1996/12/18 17:44:48 shavirin
* Added support for CC++ compiler usage.
*
* Revision 1.4 1996/12/13 22:53:18 shavirin
* Added definitions to new functions.
* ..
*
* Revision 1.3 1996/12/12 19:24:35 shavirin
* Changed definitions of WWWReadPosting() and entered new function
* WWWGetArgs(). Added WWWErrorCode definitions.
*
* Revision 1.2 1996/12/11 18:13:31 shavirin
* Main WWWInfoPtr changed to Void Pointer to hide real structure,
* that called now WWWInfoDataPtr
*
* Revision 1.1 1996/12/03 22:47:18 shavirin
* Initial revision
*
* ==========================================================================
*/
#ifndef _NCBI_WWW_
#define _NCBI_WWW_ ncbiwww
#ifndef _NCBI_
#include <ncbi.h>
#endif
#undef NLM_EXTERN
#ifdef NLM_IMPORT
#define NLM_EXTERN NLM_IMPORT
#else
#define NLM_EXTERN extern
#endif
/****************************************************************************/
/* DEFINES */
/****************************************************************************/
#define MAX_WWW_ENTRIES 32768 /* maximum number of html tags in input */
#define WWW_MAX_NAME_LEN 512 /* Limit for Name in HTML tag */
#define MISC_BROWSER 0 /* Any Browser Netscape Ver. 1 included */
#define NETSCAPE 1 /* Netscape Ver. 2 and higher */
#define EXPLORER 2 /* Microsoft Internet Explorer. Any Version */
#define COMMAND_LINE 0 /* program used from command line */
#define WWW_GET 1 /* method with ?name=value&name=value&.. form */
#define WWW_POST 2 /* input through stdin in ?..=..&..=.. form */
#define FORM_DATA 3 /* RFC 1867 multipart/form-data */
#define LIVE_SERVER_PORT 80 /* default HTTPD live port */
#define INIT_BUFF_SIZE 4028 /* temporary buffer to read from file/stdin */
/****************************************************************************/
/* TYPEDEFS */
/****************************************************************************/
typedef struct WWWEntry {
CharPtr name; /* HTML tag NAME=.. */
CharPtr val; /* HTML tag VALUE=.. */
Int4 size; /* Size of data in "val" */
} WWWEntry, PNTR WWWEntryPtr;
/* typedef VoidPtr WWWInfo; */
typedef VoidPtr WWWInfoPtr;
typedef struct WWWInfoData {
Int4 method; /* GET, POST or COMMAND_LINE */
Int4 port; /* Server port - current server */
CharPtr server_name; /* Server name - current server */
CharPtr doc_root; /* Document directory of current server */
CharPtr script_name; /* Script name - CGI program */
CharPtr host; /* remote host of client */
CharPtr address; /* remote address of client - may be proxy */
CharPtr proxied_ip; /* 'real' remote addr of client as set by proxy */
CharPtr agent; /* Label of remote client */
CharPtr query; /* Complete input buffer */
Int4 query_len; /* Length of data in input buffer */
Int4 browser; /* Value derived from Label */
WWWEntryPtr PNTR entries; /* Parced input data */
Int4 num_entries; /* Number of HTML tags */
} WWWInfoData, PNTR WWWInfoDataPtr;
typedef enum {
WWWErrOk = 0,
WWWErrNoMem = 1,
WWWErrNetwork = 2
} WWWErrorCode;
struct SWWWGetArgs_tag;
typedef struct SWWWGetArgsAttr_tag PNTR SWWWGetArgsAttr;
/****************************************************************************/
/* FINCTION DEFINITIONS */
/****************************************************************************/
#ifdef __cplusplus
extern "C" {
#endif
/* ---------------------- WWWGetEntries -------------------------
Purpose: Assuming, that input buffer is in HTTP or RFC 1867
this function converts input into array of name, value
pairs in the form of WWWEntry -es.
Parameters: num_entries - number of paires returned
WWWBuffer - main input HTTP buffer
NetscapeOK - if TRUE check for RFC 1867 will
be performed before standard processing (Not used now)
WWWBuffer_len - length of data in the WWWBuffer
Returns: Pointer to array of WWWEntry pairs
NOTE: RFC 1867 may be enabled only with Netscape Version 2 and
higher.
------------------------------------------------------------------*/
NLM_EXTERN WWWEntryPtr PNTR WWWGetEntries(Int4Ptr num_entries,
CharPtr WWWBuffer,
Boolean NetscapeOK);
NLM_EXTERN WWWEntryPtr PNTR WWWGetEntriesEx(Int4Ptr num_entries,
CharPtr WWWBuffer,
Int4 WWWBuffer_len);
/* -------------------- WWWGetEntriesFomData -----------------------
Purpose: Assuming, that input buffer is in RFC 1867
ftp://ds.internic.net/rfc/rfc1867.txt
(multipart/form-data) encoding this function
converts input into array of name, value pairs
in the form of WWWEntry -es.
Parameters: WWWBuffer - main input HTTP buffer
entries - pointer to array of WWWEntry -es
Returns: Number of WWW entries returned
NOTE: RFC 1867 may be enabled only with Netscape Version 2 and
higher.
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetEntriesFormData(WWWEntryPtr PNTR entries,
CharPtr WWWBuffer);
NLM_EXTERN Int4 WWWGetEntriesFormDataEx(WWWEntryPtr PNTR entries,
CharPtr WWWBuffer,
Int4 WWWBuffer_len);
/* ----------------------- WWWGetArgs ---------------------------
Purpose: This function read HTML input in POST, GET or
multipart/form-data encoding - depends upon
environment. If used from command-line this
function will return valid WWWInfo structure
with all field blank exept info->method, that
will be set to COMMAND_LINE.
If argc == 1 this function will read WWW buffer
from STDIN, otherwise it will treat argv[1] as
WWW buffer.
Parameters: None
Returns: WWWInfoPtr structure with processed HTTP input and
environment
NOTE: This function will filer input for non-printing
characters. Transfer of binary files is not supported.
------------------------------------------------------------------*/
NLM_EXTERN WWWErrorCode WWWGetArgs(WWWInfoPtr PNTR info);
/* ----------------------- WWWGetArgsEx ---------------------------
Purpose: Identical to previous function, but it have additional
parameter with working attributes
Parameters: attr - function's working attributes
Returns: WWWInfoPtr structure with processed HTTP input and
environment
------------------------------------------------------------------*/
NLM_EXTERN WWWErrorCode WWWGetArgsEx(WWWInfoPtr PNTR info,
SWWWGetArgsAttr attr);
/* ----------------------- WWWGetArgsAttr... -----------------------
Purpose: This functions create, destroy and set parameter's
values to SWWWGetArgsAttr structure.
NOTE: Created structure use into WWWGetArgsEx()
------------------------------------------------------------------*/
NLM_EXTERN SWWWGetArgsAttr WWWGetArgsAttr_Create(void);
NLM_EXTERN void WWWGetArgsAttr_Destroy(SWWWGetArgsAttr attr);
NLM_EXTERN Boolean WWWGetArgsAttr_SetFilter(SWWWGetArgsAttr attr,
Boolean filter_non_print);
NLM_EXTERN Boolean WWWGetArgsAttr_SetReadArgv(SWWWGetArgsAttr attr,
Boolean read_argv);
/* ---------------------- WWWReadPosting -------------------------
Purpose: This function read HTML input in POST, GET or
multipart/form-data encoding - depends upon
environment. If used from command-line this
function will return valid WWWInfo structure
with all field blank exept info->method, that
will be set to COMMAND_LINE
No more proccesing will be performed.
Parameters: None
Returns: WWWInfoPtr structure with processed HTTP input and
environment
NOTE: This function will filer input for non-printing
characters. Transfer of binary files is not supported.
------------------------------------------------------------------*/
NLM_EXTERN WWWErrorCode WWWReadPosting(WWWInfoPtr PNTR info);
/* ------------------- WWWReadFileInMemory -----------------------
Purpose: Function reads data from file or stdin into
string buffer (terminated by NULLB).
Parameters: fd - opened file
len - number of bytes to read. If this value set
to 0 file will be read until EOF or closing
external connection (for sockets).
If len != 0 NOT MORE THAN len bytes will
be read from input streem
filter - if TRUE filtering of non-printed characters
will be performed
rsize - return size of read data
Returns: Pointer to allocated buffer.
NOTE: Please be carefull with "len": function read input
absolutely differently if len == 0 or len != 0
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWReadFileInMemory(FILE *fd, Int4 len, Boolean filter);
NLM_EXTERN CharPtr WWWReadFileInMemoryEx(FILE *fd, Int4 len, Boolean filter,
Int4Ptr rsize);
/* ---------------------- WWWInfoFree -------------------------
Purpose: Free WWWInfo structure
Parameters: WWWInfo structure
Returns: None
------------------------------------------------------------------*/
NLM_EXTERN void WWWInfoFree(WWWInfoPtr info);
/* ---------------------- WWWGetWWWEntry -------------------------
Purpose: Return pointer to array of name=value tags
Parameters: WWWInfoPtr
Returns: Method used or -1 if error
------------------------------------------------------------------*/
NLM_EXTERN WWWEntryPtr PNTR WWWGetWWWEntries(WWWInfoPtr info);
/* ---------------------- WWWGetMethod -------------------------
Purpose: Return method used in WWW Request or COMMAND_LINE
Parameters: WWWInfoPtr
Returns: Method used or -1 if error
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetMethod(WWWInfoPtr info);
/* ---------------------- WWWGetBrowser -------------------------
Purpose: Return browser used in WWW Request
Parameters: WWWInfoPtr
Returns: Browser used or -1 if error
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetBrowser(WWWInfoPtr info);
/* ---------------------- WWWGetNumEntries -------------------------
Purpose: Return number of name=value tags in WWW Request
Parameters: WWWInfoPtr
Returns: Number of Entries or -1 if error
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetNumEntries(WWWInfoPtr info);
/* ---------------------- WWWGetAgent -------------------------
Purpose: Return agent used in WWW Request
Parameters: WWWInfoPtr
Returns: Agent used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetAgent(WWWInfoPtr info);
/* ---------------------- WWWGetAddress -------------------------
Purpose: Return address used in WWW Request
Parameters: WWWInfoPtr
Returns: Address used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetAddress(WWWInfoPtr info);
/* ---------------------- WWWGetDocRoot -------------------------
Purpose: Return DOCUMENT_ROOT directory of current server
Parameters: WWWInfoPtr
Returns: Document root directory or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetDocRoot(WWWInfoPtr info_in);
/* ---------------------- WWWGetProxedIP -------------------------
Purpose: Return 'real' client address as set by proxy server
Parameters: WWWInfoPtr
Returns: Host used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetProxiedIP(WWWInfoPtr info_in);
/* ---------------------- WWWGetHost -------------------------
Purpose: Return host used in WWW Request
Parameters: WWWInfoPtr
Returns: Host used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetHost(WWWInfoPtr info);
/* ---------------------- WWWGetServer -------------------------
Purpose: Return HTTPD server name used in WWW Request
Parameters: WWWInfoPtr
Returns: Server name used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetServer(WWWInfoPtr info_in);
/* ---------------------- WWWGetQuery -------------------------
Purpose: Return full query used in WWW Request
Parameters: WWWInfoPtr
Returns: Query used or NULL if error
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetQuery(WWWInfoPtr info);
/* ---------------------- WWWGetPort -------------------------
Purpose: Return port used in WWW Request
Parameters: WWWInfoPtr
Returns: Port used or -1 if error
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetPort(WWWInfoPtr info);
/* ---------------------- WWWInfoNew -------------------------
Purpose: Allocates WWWInfo structure
Parameters: None
Returns: WWWInfo structure
------------------------------------------------------------------*/
/* NLM_EXTERN WWWInfoPtr WWWInfoNew(void); */
/* ---------------------- WWWFindName -------------------------
Purpose: This function look for Name in WWW Entries structure
Parameters: info - WWWInfo structure
find - Name to find
Returns: index in WWWEntry structue if "find" found and -1 if not
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWFindName(WWWInfoPtr info, CharPtr find);
/* ---------------------- WWWFindName -------------------------
Purpose: This function look for Name in WWW Entries structure
starting from specifix index value
Parameters: info - WWWInfo structure
find - Name to find
index - index value to start with
Returns: index in WWWEntry structue if "find" found and -1 if not
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWFindNameEx(WWWInfoPtr info_in, CharPtr find, Int4 index);
/* ---------------------- WWWGetNameByIndex ----------------------
Purpose: This function get Name correspondig to specific
index.
Parameters: info - WWWInfo structure
index - Index in WWW Entries structure
Returns: Pointer to Name or NULL if index invalid
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetNameByIndex(WWWInfoPtr info, Int4 index);
/* ------------------- WWWGetValueByIndex ---------------------
Purpose: This function get Value correspondig to specific
index.
Parameters: info - WWWInfo structure
index - Index in WWW Entries structure
Returns: Pointer to Value or NULL if index invalid
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetValueByIndex(WWWInfoPtr info, Int4 index);
/* ------------------- WWWGetValueSizeByIndex ---------------------
Purpose: This function get size of Value correspondig to
specific index.
Parameters: info - WWWInfo structure
index - Index in WWW Entries structure
Returns: Number of bytes stored into the Value
------------------------------------------------------------------*/
NLM_EXTERN Int4 WWWGetValueSizeByIndex(WWWInfoPtr info, Int4 index);
/* ------------------- WWWGetValueByName ---------------------
Purpose: This function get Value correspondig to specific
Name.
Parameters: info - WWWInfo structure
name - name to look for
start - Index in WWW Entries structure to start from
Returns: Pointer to Value or NULL if Name was not found
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetValueByName(WWWInfoPtr info, CharPtr name);
/* ------------------- WWWGetValueByName ---------------------
Purpose: This function get LAST Value correspondig to specific
Name if there are more then one.
Parameters: info - WWWInfo structure
name - name to look for
start - Index in WWW Entries structure to start from
Returns: Pointer to Value or NULL if Name was not found
------------------------------------------------------------------*/
NLM_EXTERN CharPtr WWWGetLastValueByName(WWWInfoPtr info_in, CharPtr find);
/* ------------------- WWWSubstituteValue ---------------------
Purpose: This function substitute "old" value by "new"
value in WWWInfo structure.
Parameters: info_in - WWWInfo structure
old - value to change
new - new value to assign
Returns: FALSE if "old" value not found, otherwise TRUE
------------------------------------------------------------------*/
NLM_EXTERN Boolean WWWSubstituteValue(WWWInfoPtr info_in,
CharPtr old, CharPtr new_value);
/* ------------------- WWWSubstituteValueByName -------------------
Purpose: This function substitute value corresponding to "name"
by "new" value in WWWInfo structure.
Parameters: info_in - WWWInfo structure
name - corresponding name
new - new value to assign
Returns: FALSE if "name" was not found, otherwise TRUE
------------------------------------------------------------------*/
NLM_EXTERN Boolean WWWSubstituteValueByName(WWWInfoPtr info_in,
CharPtr new_value, CharPtr name);
#ifdef __cplusplus
}
#endif
#undef NLM_EXTERN
#ifdef NLM_EXPORT
#define NLM_EXTERN NLM_EXPORT
#else
#define NLM_EXTERN
#endif
#endif
|