← Back to branch summary

~ubuntu-branches/ubuntu/raring/ncbi-tools6/raring

« back to all changes in this revision

Viewing changes to connect/ncbi_socket.h

  • Committer: Package Import Robot
  • Author(s): Aaron M. Ucko
  • Date: 2011-09-05 18:55:02 UTC
  • mfrom: (1.1.11 upstream)
  • Revision ID: package-import@ubuntu.com-20110905185502-iuvmoe65ytljhckn
Tags: 6.1.20110713-1
* New upstream release.
* debian/*.symbols: update accordingly.
* make/makeshlb.unx: link libcn3dOGL.so against -lm for sqrt.
* doc/man/*.1: update for new release.
* debian/rules:
  - (VIB): add asnmacro, as upstream takes care to publish binaries thereof.
  - Retire obsolete multiarch-unaware checks for libpthread.
  - Fully modernize Debhelper usage; in particular, transition to overrides.
* debian/compat: advance to 9 per rules modernization.
* debian/ncbi-tools-bin.install: add asnmacro.
* make/makenet.unx: link asnmacro only against libraries it directly needs.
* doc/man/asnmacro.1: give asnmacro a man page.
* doc/man/Psequin.1: list it in SEE ALSO.
* network/id1arch/idfetch.c: revert redundant change (from #295110).
* Convert to multiarch.
  - debian/rules: Install libraries (and ncbithr.o) to multiarch directories.
  - debian/lib*.install: match multiarch library paths.
  - debian/control:
    + Build-Depends: debhelper (>= 8.1.3~), implying a recent dpkg-dev.
    + Set Multi-Arch: as appropriate across the board, and specify
      Pre-Depends: ${misc:Pre-Depends} for runtime libraries.
* debian/*.lintian-overrides: drop leading slashes for Lintian 2.5.x.
* debian/control: Standards-Version: 3.9.2 (already compliant).

Show diffs side-by-side

added added

removed removed

Lines of Context:
connect/ncbi_socket.h
1
1
#ifndef CONNECT___NCBI_SOCKET__H
2
2
#define CONNECT___NCBI_SOCKET__H
3
3
 
4
 
/* $Id: ncbi_socket.h,v 6.75 2010/05/06 16:49:35 kazimird Exp $
 
4
/* $Id: ncbi_socket.h,v 6.84 2011/04/15 14:44:30 kazimird Exp $
5
5
 * ===========================================================================
6
6
 *
7
7
 *                            PUBLIC DOMAIN NOTICE
38
38
 *********************************
39
39
 * Generic:
40
40
 *
 
41
 *  SOCK_InitializeAPI
 
42
 *  SOCK_ShutdownAPI
41
43
 *  SOCK_AllowSigPipeAPI
42
 
 *
43
 
 *  SOCK_InitializeAPI
44
 
 *  SOCK_ShutdownAPI
 
44
 *  SOCK_OSHandleSize
45
45
 *
46
46
 * Event trigger (handle TRIGGER):
47
47
 *
48
48
 *  TRIGGER_Create
 
49
 *  TRIGGER_Close
49
50
 *  TRIGGER_Set
50
51
 *  TRIGGER_IsSet
51
52
 *  TRIGGER_Reset
52
 
 *  TRIGGER_Close
53
53
 *
54
54
 * Listening socket (handle LSOCK):
55
55
 *
56
 
 *  LSOCK_Create
57
 
 *  LSOCK_Accept
 
56
 *  LSOCK_Create[Ex]
 
57
 *  LSOCK_Accept[Ex]
58
58
 *  LSOCK_Close
 
59
 *  LSOCK_GetOSHandle
 
60
 *  LSOCK_GetPort
59
61
 *  
60
62
 * I/O Socket (handle SOCK):
61
63
 *
63
65
 *  SOCK_CreateOnTop[Ex]
64
66
 *  SOCK_Reconnect
65
67
 *  SOCK_Shutdown
66
 
 *  SOCK_Close
 
68
 *  SOCK_Close[Ex]
67
69
 *  SOCK_Wait
68
70
 *  SOCK_Poll
69
71
 *  SOCK_SetTimeout
70
 
 *  SOCK_GetReadTimeout
71
 
 *  SOCK_GetWriteTimeout
 
72
 *  SOCK_GetTimeout
72
73
 *  SOCK_Read (including "peek" and "persistent read")
73
74
 *  SOCK_ReadLine
74
75
 *  SOCK_PushBack
77
78
 *  SOCK_Abort
78
79
 *  SOCK_GetLocalPort[Ex]
79
80
 *  SOCK_GetPeerAddress
80
 
 *  SOCK_GetPeerAddressString
81
 
 *
 
81
 *  SOCK_GetRemotePort
 
82
 *  SOCK_GetPeerAddressString[Ex]
 
83
 *  SOCK_GetOSHandle
82
84
 *  SOCK_SetReadOnWriteAPI
83
85
 *  SOCK_SetReadOnWrite
84
 
 *  SOCK_SetInterruptOnSignalAPI
85
 
 *  SOCK_SetInterruptOnSignal
86
 
 *  SOCK_SetReuseAddressAPI
87
 
 *  SOCK_SetReuseAddress
 
86
 *  SOCK_SetCork
88
87
 *  SOCK_DisableOSSendDelay
89
88
 *
90
89
 * Datagram Socket:
97
96
 *  DSOCK_RecvMsg
98
97
 *  DSOCK_WipeMsg
99
98
 *  DSOCK_SetBroadcast
 
99
 *  DSOCK_GetMessageCount
100
100
 *
101
 
 * Socket classification:
 
101
 * Socket classification & statistics:
102
102
 *
103
103
 *  SOCK_IsDatagram
104
104
 *  SOCK_IsClientSide
105
105
 *  SOCK_IsServerSide
106
106
 *  SOCK_IsUNIX
 
107
 *  SOCK_IsSecure
 
108
 *  SOCK_GetPosition
 
109
 *  SOCK_GetCount
 
110
 *  SOCK_GetTotalCount
 
111
 *
 
112
 * Settings:
 
113
 *
 
114
 *  SOCK_SetInterruptOnSignalAPI
 
115
 *  SOCK_SetInterruptOnSignal
 
116
 *  SOCK_SetReuseAddressAPI
 
117
 *  SOCK_SetReuseAddress
107
118
 *
108
119
 * Data logging:
109
120
 *
112
123
 *
113
124
 * Auxiliary:
114
125
 *
115
 
 *  SOCK_gethostname
116
126
 *  SOCK_ntoa
117
 
 *  SOCK_isip
118
 
 *  SOCK_isipEx
 
127
 *  SOCK_isip[Ex]
119
128
 *  SOCK_HostToNetShort
120
129
 *  SOCK_HostToNetLong
121
130
 *  SOCK_NetToHostShort
122
131
 *  SOCK_NetToHostLong
123
 
 *  SOCK_gethostbyname
124
 
 *  SOCK_gethostbyaddr
 
132
 *  SOCK_gethostname[Ex]
 
133
 *  SOCK_gethostbyname[Ex]
 
134
 *  SOCK_gethostbyaddr[Ex]
125
135
 *  SOCK_GetLoopbackAddress
 
136
 *  SOCK_GetLocalHostAddress
126
137
 *  SOCK_StringToHostPort
127
138
 *  SOCK_HostPortToString
128
139
 *
131
142
 *  SOCK_SetSelectInternalRestartTimeout
132
143
 *  SOCK_SetIOWaitSysAPI
133
144
 *
134
 
 *  Secure:
 
145
 * Secure Socket Layer:
135
146
 *
136
147
 *  SOCK_SetupSSL
137
148
 *
169
180
 
170
181
 
171
182
/** Forward declarations of the hidden socket internal structures, and
172
 
 * their upper-level handles to use by the LSOCK_*() and SOCK_*() API
 
183
 *  their upper-level handles to use by the LSOCK_*() and SOCK_*() API
173
184
 */
174
185
struct LSOCK_tag;                /* listening socket:  internal storage */
175
 
typedef struct LSOCK_tag* LSOCK; /* listening socket:  handle           */
 
186
typedef struct LSOCK_tag* LSOCK; /* listening socket:  handle, opaque   */
176
187
 
177
188
struct SOCK_tag;                 /* socket:  internal storage           */
178
 
typedef struct SOCK_tag*  SOCK;  /* socket:  handle                     */
 
189
typedef struct SOCK_tag*  SOCK;  /* socket:  handle, opaque             */
179
190
 
180
191
struct TRIGGER_tag;
181
192
typedef struct TRIGGER_tag* TRIGGER;
182
193
 
183
194
 
 
195
 
184
196
/******************************************************************************
185
 
 * Multi-Thread safety
 
197
 *                       Multi-Thread safety NOTICE
186
198
 *
187
199
 * If you are using this API in a multi-threaded application, and there is
188
200
 * more than one thread using this API, it is safe to call SOCK_InitializeAPI()
189
 
 * explicitly in the beginning of your main thread, before you run any other
190
 
 * threads, and to call SOCK_ShutdownAPI() after all threads are exited.
 
201
 * explicitly at the beginning of your main thread, before you run any other
 
202
 * threads, and to call SOCK_ShutdownAPI() after all threads have exited.
191
203
 *
192
204
 * As soon as the API is initialized it becomes relatively MT-safe, however
193
205
 * you still must not operate on same LSOCK or SOCK objects from different
194
 
 * threads simultaneously.
 
206
 * threads simultaneously.  Any entry point of this API will attempt to
 
207
 * initialize the API implicitly if that has not yet been previously done.
 
208
 * However, the implicit initialization gets disabled by SOCK_ShutdownAPI()
 
209
 * (explicit re-init with SOCK_InitializeAPI() is always allowed).
195
210
 *
196
211
 * A MUCH BETTER WAY of dealing with this issue is to provide your own MT
197
 
 * locking callback (see CORE_SetLOCK in "ncbi_core.h"). This will also
198
 
 * guarantee the proper MT protection should some other SOCK functions
199
 
 * start to access any static data in the future.
200
 
 *
201
 
 * @sa
202
 
 *  CORE_SetLOCK
203
 
 */
204
 
 
205
 
 
206
 
 
207
 
/******************************************************************************
208
 
 *  Error & Data Logging
209
 
 *
210
 
 * @li <b>NOTE:</b>  Use CORE_SetLOG() from "ncbi_core.h" to set log handler.
211
 
 *
212
 
 * @sa
213
 
 *  CORE_SetLOG
214
 
 */
215
 
 
216
 
/** By default ("log" == eDefault, which is eOff), data are not logged.
217
 
 * @param log
218
 
 *  To start logging the data, call this func with "log" == eOn.
219
 
 *  To stop  logging the data, call this func with "log" == eOff.
220
 
 * @return
221
 
 *  Prior setting
222
 
 * @sa
223
 
 *  SOCK_SetDataLogging
224
 
 */
225
 
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLoggingAPI
226
 
(ESwitch log
227
 
 );
228
 
 
229
 
 
230
 
/** Control the data logging for socket "sock" individually.
231
 
 * @param sock
232
 
 *  [in]  socket handle
233
 
 * @param log
234
 
 *  [in]  requested data logging
235
 
 *  To reset to the global default behavior (as set by SOCK_SetDataLoggingAPI),
236
 
 *  call this function with "log" == eDefault.
237
 
 * @return
238
 
 *  Prior setting
239
 
 * @sa
240
 
 *  SOCK_SetDataLoggingAPI, SOCK_Create, DSOCK_Create
241
 
 */
242
 
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLogging
243
 
(SOCK    sock,
244
 
 ESwitch log
245
 
 );
246
 
 
247
 
 
248
 
 
249
 
/******************************************************************************
250
 
 *   I/O restart on signals
251
 
 */
252
 
 
253
 
/** Control restartability of I/O interrupted by signals.
254
 
 * By default ("on_off" == eDefault,eOff), I/O is restartable if interrupted.
255
 
 * @param on_off
256
 
 *  [in]  eOn to cancel I/O on signals;  eOff to restart
257
 
 * @return
258
 
 *  Prior setting.
259
 
 * @sa
260
 
 *  SOCK_SetInterruptOnSignal
261
 
 */
262
 
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignalAPI
263
 
(ESwitch on_off
264
 
 );
265
 
 
266
 
 
267
 
/** Control restartability of I/O interrupted by signals on a per-socket basis.
268
 
 * eDefault causes the use of global API flag.
269
 
 * @param sock
270
 
 *  [in]  socket handle
271
 
 * @param on_off
272
 
 *  [in]  per-socket I/O restart behavior on signals
273
 
 * @return
274
 
 *  Prior setting.
275
 
 * @sa
276
 
 *  SOCK_SetInterruptOnSignalAPI, SOCK_Create, DSOCK_Create
277
 
 */
278
 
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignal
279
 
(SOCK    sock,
280
 
 ESwitch on_off
281
 
 );
282
 
 
283
 
 
284
 
 
285
 
/******************************************************************************
286
 
 *   Address reuse: EXPERIMENTAL and may be removed in the upcoming releases!
287
 
 */
288
 
 
289
 
/** Control address reuse for socket addresses taken by the API.
290
 
 * By default ("on_off" == eDefault,eOff), address is not marked
291
 
 * for reuse in SOCK, but is always reused for LSOCK.
292
 
 * @param on_off
293
 
 *  [in]  whether to turn on (eOn), turn off (eOff), or use default (eDefault)
294
 
 * @return
295
 
 *  Prior setting.
296
 
 * @sa
297
 
 *  SOCK_SetReuseAddress
298
 
 */
299
 
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReuseAddressAPI
300
 
(ESwitch on_off
301
 
 );
302
 
 
303
 
 
304
 
/** Control reuse of socket addresses on per-socket basis
305
 
 * Note: only a boolean parameter value is can be used here.
306
 
 * @param sock
307
 
 *  [in]  socket handle
308
 
 * @param on_off
309
 
 *  [in]  whether to reuse the address (true, non-zero) or not (false, zero)
310
 
 * @sa
311
 
 *  SOCK_SetReuseAddressAPI, SOCK_Create, DSOCK_Create
312
 
 */
313
 
extern NCBI_XCONNECT_EXPORT void SOCK_SetReuseAddress
314
 
(SOCK         sock,
315
 
 int/**bool*/ on_off);
316
 
 
317
 
 
318
 
 
319
 
/******************************************************************************
320
 
 *  API Initialization and Shutdown/Cleanup
321
 
 */
 
212
 * locking callback (see CORE_SetLOCK() in "ncbi_core.h").  This will also
 
213
 * ensure proper MT protection should some SOCK functions start accessing
 
214
 * any intrinsic static data (such as in case of SSL).
 
215
 *
 
216
 * The MT lock as well as other library-wide settings are also provided
 
217
 * (in most cases automatically) by CONNECT_Init() API:  for C Toolkit it gets
 
218
 * always called before [Nlm_]Main();  in C++ Toolkit it gets called by
 
219
 * most of C++ classes' ctors, except for sockets;  so if your application
 
220
 * does not use any C++ classes besides sockets, it has to set CORE_LOCK
 
221
 * explicitly, as described above.
 
222
 *
 
223
 * @sa
 
224
 *  CORE_SetLOCK, CONNECT_Init
 
225
 */
 
226
 
 
227
 
 
228
 
 
229
/******************************************************************************
 
230
 *  API Initialization, Shutdown/Cleanup, and Utility
 
231
 */
 
232
 
 
233
/** Initialize all internal/system data & resources to be used by the SOCK API.
 
234
 * @li <b>NOTE:</b>
 
235
 *  You can safely call it more than once; just, all calls after the first
 
236
 *  one will have no result. 
 
237
 * @li <b>NOTE:</b>
 
238
 *  Usually, SOCK API does not require an explicit initialization -- as it is
 
239
 *  guaranteed to initialize itself automagically, in one of API functions,
 
240
 *  when necessary.  Yet, see the "Multi Thread safety" remark above.
 
241
 * @li <b>NOTE:</b>
 
242
 *  This call, when used for the very first time in the application, enqueues
 
243
 *  SOCK_ShutdownAPI() to be called upon application exit on plaftorms that
 
244
 *  provide this functionality. In any case, the application can opt for
 
245
 *  explicit SOCK_ShutdownAPI() call when it is done with all sockets.
 
246
 * @sa
 
247
 *  SOCK_ShutdownAPI
 
248
 */
 
249
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_InitializeAPI(void);
 
250
 
 
251
 
 
252
/** Cleanup; destroy all internal/system data & resources used by the SOCK API.
 
253
 * ATTENTION:  no function from the SOCK API should be called after this call!
 
254
 * @li <b>NOTE:</b>
 
255
 *  You can safely call it more than once; just, all calls after the first
 
256
 *  one will have no result. 
 
257
 * @sa
 
258
 *  SOCK_InitializeAPI
 
259
 */
 
260
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_ShutdownAPI(void);
 
261
 
 
262
 
 
263
/** By default (on UNIX platforms) the SOCK API functions automagically call
 
264
 * "signal(SIGPIPE, SIG_IGN)" on initialization.  To prohibit this feature,
 
265
 * you must call SOCK_AllowSigPipeAPI() before you call any other
 
266
 * function from the SOCK API.
 
267
 */
 
268
extern NCBI_XCONNECT_EXPORT void SOCK_AllowSigPipeAPI(void);
 
269
 
 
270
 
 
271
/**
 
272
 * Get size of OS-dependent native socket handle
 
273
 * @return
 
274
 *  OS-dependent handle size or 0 in case of an error
 
275
 * @sa
 
276
 *  SOCK_GetOSHandle
 
277
 */
 
278
extern NCBI_XCONNECT_EXPORT size_t SOCK_OSHandleSize(void);
 
279
 
322
280
 
323
281
/** This is a helper call that can improve I/O behavior.
324
 
 * @param timeout
325
 
 *  [in]  Break down long waits on I/O into smaller chunks of at most "timeout"
326
 
 *  duration each.  This can help recover "hanging" sockets from indefinite
327
 
 *  wait and allow them to report an exceptional I/O condition.
 
282
 * @param timeslice
 
283
 *  [in]  Break down long waits on I/O into smaller intervals of at most
 
284
 *  "timeslice" duration each.  This can help recover "hanging" sockets from
 
285
 *  indefinite wait and allow them to report an exceptional I/O condition.
328
286
 * @return
329
 
 *   Previous value of the timeout
 
287
 *  Previous value of the timeslice
330
288
 * @sa
331
289
 *  SOCK_Wait, SOCK_Poll
332
290
 */
333
291
extern NCBI_XCONNECT_EXPORT const STimeout*
334
292
SOCK_SetSelectInternalRestartTimeout
335
 
(const STimeout* timeout);
 
293
(const STimeout* timeslice);
336
294
 
337
295
 
338
296
/** Selector of I/O wait system API:  auto, poll(), or select().
362
320
(ESOCK_IOWaitSysAPI api);
363
321
 
364
322
 
365
 
/** By default (on UNIX platforms) the SOCK API functions automagically call
366
 
 * "signal(SIGPIPE, SIG_IGN)" on initialization.  To prohibit this feature,
367
 
 * you must call SOCK_AllowSigPipeAPI() before you call any other
368
 
 * function from the SOCK API.
369
 
 */
370
 
extern NCBI_XCONNECT_EXPORT void SOCK_AllowSigPipeAPI(void);
371
 
 
372
 
 
373
 
/** Initialize all internal/system data & resources to be used by the SOCK API.
374
 
 * @li <b>NOTE:</b>
375
 
 *  You can safely call it more than once; just, all calls after the first
376
 
 *  one will have no result. 
377
 
 * @li <b>NOTE:</b>
378
 
 *  Usually, SOCK API does not require an explicit initialization -- as it is
379
 
 *  guaranteed to initialize itself automagically, in one of API functions,
380
 
 *  when necessary.  Yet, see the "Multi Thread safety" remark above.
381
 
 * @li <b>NOTE:</b>
382
 
 *  This call, when used for the very first time in the application, enqueues
383
 
 *  SOCK_ShutdownAPI() to be called upon application exit on plaftorms that
384
 
 *  provide this functionality. In any case, the application can opt for
385
 
 *  explicit SOCK_ShutdownAPI() call when it is done with all sockets.
386
 
 * @sa
387
 
 *  SOCK_ShutdownAPI
388
 
 */
389
 
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_InitializeAPI(void);
390
 
 
391
 
 
392
 
/** Cleanup; destroy all internal/system data & resources used by the SOCK API.
393
 
 * ATTENTION:  no function from the SOCK API should be called after this call!
394
 
 * @li <b>NOTE:</b>
395
 
 *  You can safely call it more than once; just, all calls after the first
396
 
 *  one will have no result. 
397
 
 * @sa
398
 
 *  SOCK_InitializeAPI
399
 
 */
400
 
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_ShutdownAPI(void);
401
 
 
402
 
 
403
323
 
404
324
/******************************************************************************
405
325
 *  EVENT TRIGGER
483
403
    fSOCK_LogOff       = eOff,   /** logging is inherited in Accept()ed SOCKs*/
484
404
    fSOCK_LogOn        = eOn,
485
405
    fSOCK_LogDefault   = eDefault,
 
406
    fSOCK_KeepAlive    = 8,      /** keep socket alive (if supported by OS)  */
486
407
    fSOCK_BindAny      = 0,      /** bind to 0.0.0.0 (i.e. any), default     */
487
408
    fSOCK_BindLocal    = 0x10,   /** bind to 127.0.0.1 only                  */
488
409
    fSOCK_KeepOnExec   = 0x20,   /** can be applied to all sockets           */
489
 
    fSOCK_CloseOnExec  = 0,      /** can be applied to all sockets           */
 
410
    fSOCK_CloseOnExec  = 0,      /** can be applied to all sockets, default  */
490
411
    fSOCK_Secure       = 0x40,   /** subsumes CloseOnExec regardless of Keep */
491
412
    fSOCK_KeepOnClose  = 0x80,   /** do not close OS handle on SOCK_Close[Ex]*/
492
413
    fSOCK_CloseOnClose = 0,      /** do     close OS handle on SOCK_Close[Ex]*/
500
421
 *  LISTENING SOCKET [SERVER-side]
501
422
 */
502
423
 
503
 
typedef enum { /* DEPRECATED -- DON'T USE! */
504
 
    fLSCE_LogOff      = fSOCK_LogOff,
505
 
    fLSCE_LogOn       = fSOCK_LogOn,
506
 
    fLSCE_LogDefault  = fSOCK_LogDefault,
507
 
    fLSCE_BindAny     = fSOCK_BindAny,
508
 
    fLSCE_BindLocal   = fSOCK_BindLocal,
509
 
    fLSCE_CloseOnExec = fSOCK_CloseOnExec
510
 
} ELSCE_Flags;
511
 
 
512
424
/** [SERVER-side]  Create and initialize the server-side(listening) socket
513
425
 * (socket() + bind() + listen())
514
426
 * @param port
515
 
 *  [in]  the port to listen at
 
427
 *  [in]  the port to listen at (0 to select first available)
516
428
 * @param backlog
517
429
 *  [in]  maximal # of pending connections
518
430
 *  <b>NOTE:</b> on some systems, "backlog" can be silently limited
522
434
 * @param flags
523
435
 *  [in]  special modifiers
524
436
 * @sa
525
 
 *  LSOCK_Create, LSOCK_Close
 
437
 *  LSOCK_Create, LSOCK_Close, LSOCK_GetPort
526
438
 */
527
439
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_CreateEx
528
440
(unsigned short port,    
607
519
 * @param handle_size
608
520
 *  The exact(!) size of the expected OS handle
609
521
 * @sa
610
 
 *  SOCK_GetOSHandle
 
522
 *  SOCK_OSHandleSize, SOCK_GetOSHandle
611
523
 */
612
524
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_GetOSHandle
613
525
(LSOCK  lsock,
614
526
 void*  handle_buf, 
615
 
 size_t  
 
527
 size_t handle_size
 
528
 );
 
529
 
 
530
 
 
531
/** Get socket port number, which it listens on.
 
532
 * The returned port is either one specified when the socket was created,
 
533
 * or an automatically assigned number if LSOCK_Create provided the port as 0.
 
534
 * @param lsock
 
535
 *  [in]  socket handle 
 
536
 * @param byte_order
 
537
 *  [in]  byte order for port on return
 
538
 * @return
 
539
 *  Listening port number in requested byte order, or 0 in case of an error.
 
540
 * @sa
 
541
 *  LSOCK_Create
 
542
 */
 
543
extern NCBI_XCONNECT_EXPORT unsigned short LSOCK_GetPort
 
544
(LSOCK         lsock,
 
545
 ENH_ByteOrder byte_order
616
546
 );
617
547
 
618
548
 
619
549
 
620
550
/******************************************************************************
621
 
 *  SOCKET
 
551
 *  SOCKET (connection-oriented)
622
552
 */
623
553
 
624
554
/** [CLIENT-side]  Connect client to another(server-side, listening) socket
676
606
 );
677
607
 
678
608
 
679
 
/** SOCK_Close behavior for SOCKs created on top of OS handles.
680
 
 * @sa
681
 
 *  SOCK_Close, SOCK_CreateOnTop, SOCK_CreateOnTopEx
682
 
 */
683
 
typedef enum { /* DEPRECATED -- DON'T USE */
684
 
    eSCOT_KeepOnClose  = fSOCK_KeepOnClose,
685
 
    eSCOT_CloseOnClose = fSOCK_CloseOnClose
686
 
} ESCOT_OnClose;
687
 
 
688
609
/** [SERVER-side]  Create a socket on top of OS-dependent "handle"
689
610
 * (file descriptor on Unix, SOCKET on MS-Windows).  Returned socket
690
611
 * is not reopenable to its default peer (SOCK_Reconnect may not specify
888
809
 *        - eIO_Timeout (after the specified amount of time was spent idle), or
889
810
 *        - eIO_Interrupted (if signal came while the waiting was in progress).
890
811
 * @li <b>NOTE 5:</b> For datagram sockets, the readiness for reading is
891
 
 *        determined by message data latched since last message receive call
892
 
 *        (DSOCK_RecvMsg).
893
 
 * @li <b>NOTE 6:</b> This call allows intermixture of stream and
894
 
 *        datagram sockets.
895
 
 * @li <b>NOTE 7:</b> This call can cause some socket I/O in those sockets
 
812
 *        determined by the message data latched since last message receive
 
813
 *        call, DSOCK_RecvMsg.
 
814
 * @li <b>NOTE 6:</b> This call allows intermixture of stream, datagram and
 
815
 *        listening sockets, as well as triggers.
 
816
 * @li <b>NOTE 7:</b> This call may cause some socket I/O in those sockets
896
817
 *        marked for read-on-write and those with pending connection or
897
818
 *        output data.
898
819
 * @param n
912
833
 );
913
834
 
914
835
 
915
 
 
916
 
/** GENERIC POLLABLE INTERFACE, please see above for explanations
917
 
 */
918
 
struct SPOLLABLE_tag;
919
 
typedef struct SPOLLABLE_tag* POLLABLE;
920
 
 
921
 
typedef struct {
922
 
    POLLABLE  poll;
923
 
    EIO_Event event;
924
 
    EIO_Event revent;
925
 
} SPOLLABLE_Poll;
926
 
 
927
 
/**
928
 
 * @param n
929
 
 *
930
 
 * @param polls[]
931
 
 *
932
 
 * @param timeout
933
 
 *
934
 
 * @param n_ready
935
 
 *
936
 
 */
937
 
extern NCBI_XCONNECT_EXPORT EIO_Status POLLABLE_Poll
938
 
(size_t          n,
939
 
 SPOLLABLE_Poll  polls[],
940
 
 const STimeout* timeout,
941
 
 size_t*         n_ready
942
 
 );
943
 
 
944
 
 
945
 
/**
946
 
 * @return
947
 
 *  Return 0 if conversion cannot be made; otherwise converted handle
948
 
 */
949
 
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromSOCK   (SOCK);
950
 
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromLSOCK  (LSOCK);
951
 
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromTRIGGER(TRIGGER);
952
 
extern NCBI_XCONNECT_EXPORT SOCK     POLLABLE_ToSOCK   (POLLABLE);
953
 
extern NCBI_XCONNECT_EXPORT LSOCK    POLLABLE_ToLSOCK  (POLLABLE);
954
 
extern NCBI_XCONNECT_EXPORT TRIGGER  POLLABLE_ToTRIGGER(POLLABLE);
955
 
 
956
 
 
957
836
/** Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs).
958
837
 * If "timeout" is NULL then set the timeout to be infinite;
959
838
 * @li <b>NOTE:</b> the default timeout is infinite (to wait indefinitely).
1206
1085
 * @param trueport
1207
1086
 *  [in] non-zero causes to refetch / no-cache port from the network layer
1208
1087
 * @param byte_order
1209
 
 *  [in] port byte order
 
1088
 *  [in] byte order for port on return
1210
1089
 * @return
1211
 
 *  If "network_byte_order" is true(non-zero) then return the port in the
1212
 
 *  network byte order; otherwise return it in the local host byte order.
 
1090
 *  The port number in requested byte order, or 0 in case of an error.
1213
1091
 * @sa
1214
1092
 *  SOCK_GetLocalPort
1215
1093
 */
1227
1105
 * @param sock
1228
1106
 *  [in] socket handle
1229
1107
 * @param byte_order
1230
 
 *  [in] port byte order
 
1108
 *  [in] byte order for port on return
1231
1109
 * @return
1232
 
 *  If "network_byte_order" is true(non-zero) then return the port in the
1233
 
 *  network byte order; otherwise return it in the local host byte order.
 
1110
 *  Local port number in requested byte order, or 0 in case of an error.
1234
1111
 * @sa
1235
1112
 *  SOCK_GetLocalPortEx
1236
1113
 */
1240
1117
 );
1241
1118
 
1242
1119
 
1243
 
/** Get host and port of the socket's peer.
 
1120
/** Get host and port of the socket's peer (remote end).
1244
1121
 * @param sock
1245
1122
 *  [in]  socket handle
1246
1123
 * @param host
1247
 
 *  [out] the peer's host (can be NULL)
 
1124
 *  [out] the peer's host (can be NULL, then not filled in)
1248
1125
 * @param port
1249
 
 *  [out] the peer's port (can be NULL)
 
1126
 *  [out] the peer's port (can be NULL, then not filled in)
1250
1127
 * @param byte_order
1251
 
 *  [in] host/port byte order
 
1128
 *  [in]  byte order for either host or port, or both, on return
1252
1129
 * @return
1253
 
 *  If "network_byte_order" is true(non-zero) then return the host/port in the
1254
 
 *  network byte order; otherwise return them in the local host byte order.
 
1130
 *  Host/port addresses in requested byte order, or 0 in case of an error.
 
1131
 * @sa
 
1132
 *  SOCK_GetLocalPort
1255
1133
 */
1256
1134
extern NCBI_XCONNECT_EXPORT void SOCK_GetPeerAddress
1257
1135
(SOCK            sock,
1261
1139
 );
1262
1140
 
1263
1141
 
 
1142
/** Get remote port of the socket (the port it is connected to).
 
1143
 * The call is provided as a counterpart for SOCK_GetLocalPort(), and is
 
1144
 * equivalent to calling SOCK_GetPeerAddress(sock, 0, &port, byte_order).
 
1145
 * @param sock
 
1146
 *  [in]  socket handle
 
1147
 * @param byte_order
 
1148
 *  [in]  byte order for port on return
 
1149
 * @return
 
1150
 *  Remote port number in requested byte order, or 0 in case of an error.
 
1151
 * @sa
 
1152
 *  SOCK_GetPeerAddress, SOCK_GetLocalPort
 
1153
 */
 
1154
extern NCBI_XCONNECT_EXPORT unsigned short SOCK_GetRemotePort
 
1155
(SOCK            sock,
 
1156
 ENH_ByteOrder   byte_order
 
1157
 );
 
1158
 
 
1159
 
1264
1160
/** Get textual representation of the socket's peer.
1265
1161
 * For INET domain sockets, the result is of the form "aaa.bbb.ccc.ddd:ppppp";
1266
1162
 * for UNIX domain socket, the result is the name of the socket's file.
1305
1201
 *  [out] pointer to a memory area to put the OS handle at
1306
1202
 * @param handle_size
1307
1203
 *  [in]  the exact(!) size of the expected OS handle
 
1204
 * @sa
 
1205
 *  SOCK_OSHandleSize
1308
1206
 */
1309
1207
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_GetOSHandle
1310
1208
(SOCK   sock,
1313
1211
 );
1314
1212
 
1315
1213
 
1316
 
/** By default ("on_off" == eDefault,eOff), sockets will not try to read data
1317
 
 * from inside SOCK_Write(). If you want to automagically upread the data
1318
 
 * (and cache it in the internal socket buffer) when the write operation
1319
 
 * is not immediately available, call this func with "on_off" == eOn.
 
1214
/** By default, sockets will not try to read data from inside SOCK_Write().
 
1215
 * If you want to automagically upread the data (and cache it in the internal
 
1216
 * socket buffer) when the write operation is not immediately available,
 
1217
 * call this func with "on_off" == eOn.
 
1218
 * Pass "on_off" as eDefault to get current setting.
1320
1219
 * @param on_off
1321
1220
 *
1322
1221
 * @return
1323
 
 *  Prior setting.
 
1222
 *  Prior setting
1324
1223
 */
1325
1224
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWriteAPI
1326
1225
(ESwitch on_off
1335
1234
 * @param on_off
1336
1235
 *
1337
1236
 * @return
1338
 
 *  Prior setting.
 
1237
 *  Prior setting
1339
1238
 */
1340
1239
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWrite
1341
1240
(SOCK    sock,
1344
1243
 
1345
1244
 
1346
1245
/** Control OS-defined send strategy by disabling/enabling TCP
 
1246
 * layer to send incomplete network frames (packets).
 
1247
 * With the "cork" set on, data gets always buffered until a complete
 
1248
 * hardware packet is full (or connection is about to close), and only
 
1249
 * then is sent out to the medium.
 
1250
 * The setting cancels any effects of SOCK_DisableOSSendDelay().
 
1251
 * @param sock
 
1252
 *  [in]  socket handle [stream socket only]
 
1253
 * @param on_off
 
1254
 *  [in]  1 to set the cork; 0 to remove the cork
 
1255
 * @sa
 
1256
 *  SOCK_DisableOSSendDelay
 
1257
 */
 
1258
extern NCBI_XCONNECT_EXPORT void SOCK_SetCork
 
1259
(SOCK         sock,
 
1260
 int/**bool*/ on_off  
 
1261
 );
 
1262
 
 
1263
 
 
1264
/** Control OS-defined send strategy by disabling/enabling TCP
1347
1265
 * Nagle algorithm that packs multiple requests into a single
1348
 
 * frame and thus transferring data in fewer transactions,
 
1266
 * packet and thus transferring data in fewer transactions,
1349
1267
 * miminizing the network traffic and bursting the throughput.
1350
1268
 * Some applications, however, may find it useful to disable this
1351
1269
 * default behavior for the sake of their performance increase
1352
1270
 * (like in case of short transactions otherwise held by the system
1353
1271
 * to be possibly coalesced into larger chunks).
 
1272
 * The setting cancels any effects of SOCK_SetCork().
1354
1273
 * @param sock
1355
 
 *  [in]  socket handle
 
1274
 *  [in]  socket handle [stream socket only]
1356
1275
 * @param on_off
1357
 
 *
1358
 
 * NB: use true to disable; false to enable
 
1276
 *  [in]  1 to disable the send delay; 0 to enable the send delay
 
1277
 * @sa
 
1278
 *  SOCK_SetCork
1359
1279
 */
1360
1280
extern NCBI_XCONNECT_EXPORT void SOCK_DisableOSSendDelay
1361
1281
(SOCK         sock,
1365
1285
 
1366
1286
 
1367
1287
/******************************************************************************
1368
 
 *  Connectionless (datagram) sockets
 
1288
 *  DATAGRAM SOCKETS (connectionless)
1369
1289
 *
1370
1290
 *  How the datagram exchange API works:
1371
1291
 *
1406
1326
 *  buffers correspondingly.
1407
1327
 */
1408
1328
 
1409
 
/**
1410
 
 * @param sock
1411
 
 *  [out] socket created
1412
 
 */
1413
 
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Create
1414
 
(SOCK*           sock                                
1415
 
 );
1416
1329
 
1417
1330
/**
1418
1331
 * @param sock
1425
1338
 TSOCK_Flags     flags
1426
1339
 );
1427
1340
 
 
1341
 
 
1342
/** Same as DSOCK_CreateEx(, fSOCK_LogDefault)
 
1343
 * @param sock
 
1344
 *  [out] socket created
 
1345
 */
 
1346
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Create
 
1347
(SOCK*           sock                                
 
1348
 );
 
1349
 
 
1350
 
1428
1351
/**
1429
1352
 * @param sock
1430
1353
 *  [in] SOCK from DSOCK_Create[Ex]()
1436
1359
 unsigned short  port                  
1437
1360
 );
1438
1361
 
 
1362
 
1439
1363
/**
1440
1364
 * @param sock
1441
1365
 *  [in] SOCK from DSOCK_Create[Ex]()
1450
1374
 unsigned short  port                   
1451
1375
 );
1452
1376
 
 
1377
 
1453
1378
/**
1454
1379
 * @param sock
1455
1380
 *  [in] SOCK from DSOCK_Create[Ex]()
1461
1386
 const STimeout* timeout            
1462
1387
 );
1463
1388
 
 
1389
 
1464
1390
/**
1465
1391
 * @param sock
1466
1392
 *  [in] SOCK from DSOCK_Create[Ex]()
1481
1407
 size_t          datalen               
1482
1408
 );
1483
1409
 
 
1410
 
1484
1411
/**
1485
1412
 * @param sock
1486
1413
 *  [in] SOCK from DSOCK_Create[Ex]()
1507
1434
 unsigned short* sender_port            
1508
1435
);
1509
1436
 
 
1437
 
1510
1438
/**
1511
1439
 * @param sock
1512
1440
 *  [in] SOCK from DSOCK_Create[Ex]()
1529
1457
 int/**bool*/    broadcast             
1530
1458
 );
1531
1459
 
 
1460
/**
 
1461
 * @param sock
 
1462
 *  [in] socket handle (datagram socket only)
 
1463
 * @param direction
 
1464
 *  [in] either eIO_Read or eIO_Write
 
1465
 * @return
 
1466
 *  Total number of messages sent or received through this datagram socket.
 
1467
 */
 
1468
extern NCBI_XCONNECT_EXPORT TNCBI_BigCount DSOCK_GetMessageCount
 
1469
(SOCK      sock,
 
1470
 EIO_Event direction
 
1471
 );
 
1472
 
1532
1473
 
1533
1474
 
1534
1475
/******************************************************************************
1535
 
 *  Type information for SOCK sockets
 
1476
 *  Type & statistics information for SOCK sockets
1536
1477
 */
1537
1478
 
1538
1479
 
1586
1527
extern NCBI_XCONNECT_EXPORT int/**bool*/ SOCK_IsSecure(SOCK sock);
1587
1528
 
1588
1529
 
 
1530
/**
 
1531
 * @param sock
 
1532
 *  [in] socket handle
 
1533
 * @param direction
 
1534
 *  [in] either eIO_Read or eIO_Write
 
1535
 * @return
 
1536
 *  Current read or write logical position, which takes any pending
 
1537
 *  (i.e. unread or unwritten) data into account.
 
1538
 */
 
1539
extern NCBI_XCONNECT_EXPORT TNCBI_BigCount SOCK_GetPosition
 
1540
(SOCK      sock,
 
1541
 EIO_Event direction
 
1542
 );
 
1543
 
 
1544
 
 
1545
/**
 
1546
 * @param sock
 
1547
 *  [in] socket handle
 
1548
 * @param direction
 
1549
 *  [in] either eIO_Read or eIO_Write
 
1550
 * @return
 
1551
 *  Count of bytes actually read or written through this socket in the current
 
1552
 *  session. For datagram sockets the count applies for the last message only;
 
1553
 *  for stream sockets it counts only since last accept or connect event.
 
1554
 */
 
1555
extern NCBI_XCONNECT_EXPORT TNCBI_BigCount SOCK_GetCount
 
1556
(SOCK      sock,
 
1557
 EIO_Event direction
 
1558
 );
 
1559
 
 
1560
 
 
1561
/**
 
1562
 * @param sock
 
1563
 *  [in] socket handle
 
1564
 * @param direction
 
1565
 *  [in] either eIO_Read or eIO_Write
 
1566
 * @return
 
1567
 *  Total number of bytes transferred through the socket in its lifetime.
 
1568
 */
 
1569
extern NCBI_XCONNECT_EXPORT TNCBI_BigCount SOCK_GetTotalCount
 
1570
(SOCK      sock,
 
1571
 EIO_Event direction
 
1572
 );
 
1573
 
 
1574
 
 
1575
/******************************************************************************
 
1576
 *   I/O restart on signals
 
1577
 */
 
1578
 
 
1579
/** Control restartability of I/O interrupted by signals.
 
1580
 * By default I/O is restartable if interrupted.
 
1581
 * Pass "on_off" as eDefault to get the current setting.
 
1582
 * @param on_off
 
1583
 *  [in]  eOn to cancel I/O on signals;  eOff to restart
 
1584
 * @return
 
1585
 *  Prior setting
 
1586
 * @sa
 
1587
 *  SOCK_SetInterruptOnSignal
 
1588
 */
 
1589
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignalAPI
 
1590
(ESwitch on_off
 
1591
 );
 
1592
 
 
1593
 
 
1594
/** Control restartability of I/O interrupted by signals on a per-socket basis.
 
1595
 * eDefault causes the use of global API flag.
 
1596
 * @param sock
 
1597
 *  [in]  socket handle
 
1598
 * @param on_off
 
1599
 *  [in]  per-socket I/O restart behavior on signals
 
1600
 * @return
 
1601
 *  Prior setting
 
1602
 * @sa
 
1603
 *  SOCK_SetInterruptOnSignalAPI, SOCK_Create, DSOCK_Create
 
1604
 */
 
1605
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignal
 
1606
(SOCK    sock,
 
1607
 ESwitch on_off
 
1608
 );
 
1609
 
 
1610
 
 
1611
/******************************************************************************
 
1612
 *   Address reuse: EXPERIMENTAL and may be removed in the upcoming releases!
 
1613
 */
 
1614
 
 
1615
/** Control address reuse for socket addresses taken by the API.
 
1616
 * By default address is not marked for reuse in SOCK,
 
1617
 * but is always reused for LSOCK.
 
1618
 * Pass "on_off" as eDefault to get the current setting.
 
1619
 * @param on_off
 
1620
 *  [in]  whether to turn on (eOn), turn off (eOff) or get current (eDefault)
 
1621
 * @return
 
1622
 *  Prior setting
 
1623
 * @sa
 
1624
 *  SOCK_SetReuseAddress
 
1625
 */
 
1626
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReuseAddressAPI
 
1627
(ESwitch on_off
 
1628
 );
 
1629
 
 
1630
 
 
1631
/** Control reuse of socket addresses on per-socket basis
 
1632
 * Note: only a boolean parameter value is can be used here.
 
1633
 * @param sock
 
1634
 *  [in]  socket handle
 
1635
 * @param on_off
 
1636
 *  [in]  whether to reuse the address (true, non-zero) or not (false, zero)
 
1637
 * @sa
 
1638
 *  SOCK_SetReuseAddressAPI, SOCK_Create, DSOCK_Create
 
1639
 */
 
1640
extern NCBI_XCONNECT_EXPORT void SOCK_SetReuseAddress
 
1641
(SOCK         sock,
 
1642
 int/**bool*/ on_off);
 
1643
 
 
1644
 
 
1645
/******************************************************************************
 
1646
 *  Error & Data Logging
 
1647
 *
 
1648
 * @li <b>NOTE:</b>  Use CORE_SetLOG() from "ncbi_core.h" to set log handler.
 
1649
 *
 
1650
 * @sa
 
1651
 *  CORE_SetLOG
 
1652
 */
 
1653
 
 
1654
/** By default data are not logged.
 
1655
 * @param log
 
1656
 *  To start logging the data, call this func with "log" == eOn.
 
1657
 *  To stop  logging the data, call this func with "log" == eOff.
 
1658
 *  To get current log switch, call this func with "log" == eDefault.
 
1659
 * @return
 
1660
 *  Prior setting
 
1661
 * @sa
 
1662
 *  SOCK_SetDataLogging
 
1663
 */
 
1664
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLoggingAPI
 
1665
(ESwitch log
 
1666
 );
 
1667
 
 
1668
 
 
1669
/** Control the data logging for socket "sock" individually.
 
1670
 * @param sock
 
1671
 *  [in]  socket handle
 
1672
 * @param log
 
1673
 *  [in]  requested data logging
 
1674
 *  To reset to the global default behavior (as set by SOCK_SetDataLoggingAPI),
 
1675
 *  call this function with "log" == eDefault.
 
1676
 * @return
 
1677
 *  Prior setting
 
1678
 * @sa
 
1679
 *  SOCK_SetDataLoggingAPI, SOCK_Create, DSOCK_Create
 
1680
 */
 
1681
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLogging
 
1682
(SOCK    sock,
 
1683
 ESwitch log
 
1684
 );
 
1685
 
 
1686
 
 
1687
 
 
1688
/******************************************************************************
 
1689
 * GENERIC POLLABLE INTERFACE, please see SOCK_Poll() above for explanations
 
1690
 */
 
1691
 
 
1692
 
 
1693
/*fwdecl; opaque*/
 
1694
struct SPOLLABLE_tag;
 
1695
typedef struct SPOLLABLE_tag* POLLABLE;
 
1696
 
 
1697
typedef struct {
 
1698
    POLLABLE  poll;
 
1699
    EIO_Event event;
 
1700
    EIO_Event revent;
 
1701
} SPOLLABLE_Poll;
 
1702
 
 
1703
/**
 
1704
 * @param n
 
1705
 *
 
1706
 * @param polls[]
 
1707
 *
 
1708
 * @param timeout
 
1709
 *
 
1710
 * @param n_ready
 
1711
 *
 
1712
 */
 
1713
extern NCBI_XCONNECT_EXPORT EIO_Status POLLABLE_Poll
 
1714
(size_t          n,
 
1715
 SPOLLABLE_Poll  polls[],
 
1716
 const STimeout* timeout,
 
1717
 size_t*         n_ready
 
1718
 );
 
1719
 
 
1720
 
 
1721
/**
 
1722
 * @return
 
1723
 *  Return 0 if conversion cannot be made; otherwise the converted handle
 
1724
 */
 
1725
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromSOCK   (SOCK);
 
1726
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromLSOCK  (LSOCK);
 
1727
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromTRIGGER(TRIGGER);
 
1728
extern NCBI_XCONNECT_EXPORT SOCK     POLLABLE_ToSOCK   (POLLABLE);
 
1729
extern NCBI_XCONNECT_EXPORT LSOCK    POLLABLE_ToLSOCK  (POLLABLE);
 
1730
extern NCBI_XCONNECT_EXPORT TRIGGER  POLLABLE_ToTRIGGER(POLLABLE);
 
1731
 
 
1732
 
1589
1733
 
1590
1734
/******************************************************************************
1591
1735
 *  AUXILIARY network-specific functions (added for the portability reasons)
1593
1737
 
1594
1738
 
1595
1739
/**
1596
 
 * @param name
1597
 
 *  [out] (guaranteed to be '\0'-terminated)
1598
 
 * @param namelen
1599
 
 *  [in]  max # of bytes allowed to put to "name" 
1600
 
 * @return
1601
 
 *  Zero on success, non-zero on error.  See BSD gethostname().
1602
 
 *  On error "name" returned emptied (name[0] == '\0').
1603
 
 */
1604
 
extern NCBI_XCONNECT_EXPORT int SOCK_gethostname
1605
 
(char*  name,
1606
 
 size_t namelen
1607
 
 );
1608
 
 
1609
 
 
1610
 
/**
1611
1740
 * @param addr
1612
1741
 *  [in]  must be in the network byte-order
1613
1742
 * @param buf
1685
1814
#define        SOCK_ntohs SOCK_htons
1686
1815
 
1687
1816
 
 
1817
/**
 
1818
 * @param name
 
1819
 *  [out] (guaranteed to be '\0'-terminated)
 
1820
 * @param namelen
 
1821
 *  [in]  max # of bytes allowed to put to "name" 
 
1822
 * @param log
 
1823
 *  [in]  whether to log failures
 
1824
 * @return
 
1825
 *  Zero on success, non-zero on error.  See BSD gethostname().
 
1826
 *  On error "name" returned emptied (name[0] == '\0').
 
1827
 * @sa
 
1828
 *  SOCK_gethostname
 
1829
 */
 
1830
extern NCBI_XCONNECT_EXPORT int SOCK_gethostnameEx
 
1831
(char*   name,
 
1832
 size_t  namelen,
 
1833
 ESwitch log
 
1834
 );
 
1835
 
 
1836
 
 
1837
/** Same as SOCK_gethostnameEx(,,eOff)
 
1838
 * @sa
 
1839
 *  SOCK_gethostnameEx
 
1840
 */
 
1841
extern NCBI_XCONNECT_EXPORT int SOCK_gethostname
 
1842
(char*  name,
 
1843
 size_t namelen
 
1844
 );
 
1845
 
 
1846
 
1688
1847
/** 
1689
1848
 * @param hostname
1690
 
 *  [in] return current host address if hostname is 0 
 
1849
 *  [in] specified host, or the current host if hostname is 0 
 
1850
 * @param log
 
1851
 *  [in] whether to log failures
1691
1852
 * @return
1692
1853
 *  INET host address (in network byte order) of the
1693
1854
 *  specified host (or local host, if hostname is passed as NULL),
1694
1855
 *  which can be either domain name or an IP address in
1695
1856
 *  dotted notation (e.g. "123.45.67.89\0"). Return 0 on error.
1696
1857
 *  @li <b>NOTE:</b> "0.0.0.0" and "255.255.255.255" are considered invalid.
 
1858
 * @sa
 
1859
 *  SOCK_gethostbyname, SOCK_gethostname
 
1860
 */
 
1861
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_gethostbynameEx
 
1862
(const char* hostname,
 
1863
 ESwitch     log
 
1864
 );
 
1865
 
 
1866
 
 
1867
/** Same as SOCK_gethostbynameEx(,eOff)
 
1868
 * @sa
 
1869
 *  SOCK_gethostbynameEx
1697
1870
 */
1698
1871
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_gethostbyname
1699
1872
(const char* hostname
1709
1882
 *  [out] buffer to put the name to 
1710
1883
 * @param namelen
1711
1884
 *  [in]  size (bytes) of the buffer above 
 
1885
 * @param log
 
1886
 *  [in]  whether to log failures
1712
1887
 * @return
1713
1888
 *  Value 0
1714
1889
 *  means error, while success is denoted by the 'name' argument returned.
1715
1890
 *  Note that on error the name returned emptied (name[0] == '\0').
 
1891
 * @sa
 
1892
 *  SOCK_gethostbyaddr
 
1893
 */
 
1894
extern NCBI_XCONNECT_EXPORT char* SOCK_gethostbyaddrEx
 
1895
(unsigned int addr,
 
1896
 char*        name,
 
1897
 size_t       namelen,
 
1898
 ESwitch      log
 
1899
 );
 
1900
 
 
1901
 
 
1902
/** Same as SOCK_gethostbyaddrEx(,,eOff)
 
1903
 * @sa
 
1904
 *  SOCK_gethostbyaddrEx
1716
1905
 */
1717
1906
extern NCBI_XCONNECT_EXPORT char* SOCK_gethostbyaddr
1718
 
(unsigned int addr,  
1719
 
 char*        name,   
1720
 
 size_t       namelen  
 
1907
(unsigned int addr,
 
1908
 char*        name,
 
1909
 size_t       namelen
1721
1910
 );
1722
1911
 
1723
1912