59
59
typedef struct SSERV_IterTag* SERV_ITER;
62
/* Create an iterator for the iterative server lookup.
63
* Connection information 'net_info' can be a NULL pointer, which means
64
* not to make any network connections (only LBSMD will be consulted). If
65
* 'net_info' is not NULL, LBSMD is consulted first (unless 'net_info->lb_disable'
66
* is non-zero, meaning to skip LBSMD), and then DISPD is consulted (using
67
* the information provided) but only if mapping with LBSMD (if any)
68
* has failed. This scheme permits to use any combination of service mappers.
69
* Note that if 'info' is not NULL then non-zero value of 'info->stateless'
70
* forces 'types' to have 'fSERV_StatelessOnly' set.
71
* NB: 'nbo' in comments denotes parameters coming in network byte order.
62
/* Create an iterator for sequential server lookup.
63
* Connection information 'net_info' can be a NULL pointer, which means not to
64
* make any network connections (only LOCAL/LBSMD mappers will be consulted).
65
* If 'net_info' is not NULL, LOCAL/LBSMD are consulted first, and then DISPD
66
* is consulted last (using the connection information provided) but only if
67
* mapping with LOCAL/LBSMD (if any occurred) has failed. Registry
68
* section [CONN], keys LOCAL_DISABLE, LBSMD_DISABLE, and DISPD_DISABLE
69
* (which can be overridden from the environment variables CONN_LOCAL_DISABLE,
70
* CONN_LBSMD_DISABLE, and CONN_DISPD_DISABLE, respectively) can be used to
71
* skip respective service mappers. This scheme permits to use any
72
* combination of the service mappers (local/lbsmd/network-based).
73
* Note that if 'net_info' is not NULL then non-zero value of
74
* 'net_info->stateless' forces 'types' to have the 'fSERV_StatelessOnly'
76
* NB: 'nbo' in comments denotes parameters coming in network byte order;
77
* 'hbo' stands for 'host byte order'.
74
80
/* Allocate an iterator and consult either local database (if present),
75
81
* or network database, using all default communication parameters
76
* found in registry and environment variables (implicit parameter
77
* 'info' found in two subsequent variations of this call is filled out
78
* internally by ConnNetInfo_Create(service) and then automatically used).
82
* found both in registry and environment variables (here the implicit
83
* parameter 'net_info', which has to be explicitly passed in the two
84
* subsequent variations of this call, is filled out internally by
85
* ConnNetInfo_Create(service), and then automatically used).
79
86
* NOTE that no preferred host (0) is set in the resultant iterator.
81
88
extern NCBI_XCONNECT_EXPORT SERV_ITER SERV_OpenSimple
82
(const char* service /* service name */
89
(const char* service /* service name */
86
/* Special values for preferred_host parameter */
87
#define SERV_LOCALHOST ((unsigned int)(~0UL))
88
#define SERV_ANYHOST 0 /* default, may be used as just 0 in code*/
92
/* Special values for 'preferred_host' parameter */
93
#define SERV_LOCALHOST ((unsigned int)(~0UL))
94
#define SERV_ANYHOST 0 /* default, may be used as just 0 */
91
96
/* Special "type" bit values that may be combined with server types */
93
/* Do reverse DNS translation of the resulting info */
94
fSERV_ReverseDns = 0x40000000,
95
/* Allows to get even dead services (not off ones!) */
96
fSERV_Promiscuous = 0x20000000
98
/* Allows to get even dead services (but not off ones!) */
99
fSERV_Promiscuous = 0x40000000, /* NB: all preference params are ignored*/
100
/* Do reverse DNS translation of the would-be resulting info */
101
fSERV_ReverseDns = 0x20000000,
102
/* Only stateless servers should be returned */
103
fSERV_Stateless = 0x10000000,
104
fSERV_All = 0x0000FFFF,
97
106
} ESERV_SpecialType;
107
typedef unsigned int TSERV_Type; /* Bitwise OR of ESERV_[Special]Type */
109
/* Simplified (uncluttered) type to use in 'skip' parameter below */
110
typedef const SSERV_Info* SSERV_InfoCPtr;
100
112
extern NCBI_XCONNECT_EXPORT SERV_ITER SERV_OpenEx
101
(const char* service, /* service name */
102
TSERV_Type types, /* mask of type(s) of servers requested */
103
unsigned int preferred_host,/* preferred host to use service on, nbo */
104
const SConnNetInfo* net_info, /* connection information */
105
const SSERV_Info* const skip[], /* array of servers NOT to select */
106
size_t n_skip /* number of servers in preceding array */
113
(const char* service, /* service name */
114
TSERV_Type types, /* mask of type(s) of servers requested */
115
unsigned int preferred_host,/* preferred host to use service on, nbo*/
116
const SConnNetInfo* net_info, /* connection information */
117
const SSERV_InfoCPtr skip[], /* array of servers NOT to select */
118
size_t n_skip /* number of servers in preceding array */
110
121
extern NCBI_XCONNECT_EXPORT SERV_ITER SERV_Open
111
(const char* service,
113
unsigned int preferred_host,
114
const SConnNetInfo* net_info
122
(const char* service,
124
unsigned int preferred_host,
125
const SConnNetInfo* net_info
118
129
/* Get the next server meta-address, optionally accompanied by host
119
130
* environment, specified in LBSMD configuration file on that host.
120
131
* Return 0 if no more servers were found for the service requested
121
* (parameter 'host_info' remains untouched in this case).
132
* (the pointer to 'host_info' remains untouched in this case).
122
133
* Only when completing successfully, i.e. returning non-NULL info,
123
* this function can also provide the host information as follows: if
134
* this function can also provide host information as follows: if
124
135
* 'host_info' parameter is passed as a non-NULL pointer, then a copy of the
125
* host information is allocated, and pointer to it is stored in 'host_info'.
136
* host information is allocated, and the pointer is stored at *host_info.
126
137
* Using this information, various host parameters like load, host
127
138
* environment, number of CPUs can be retrieved (see ncbi_host_info.h).
128
* NOTE: Application program should NOT destroy returned server info:
139
* Resulting DNS server info (only if coming out first) may contain 0
140
* in the host field to donote that the name is known but is currently down.
141
* NOTE: Application program should NOT destroy the returned server info:
129
142
* it will be freed automatically upon iterator destruction.
130
* On the other hand, host information has to be explicitly free()'d
131
* when no longer needed.
143
* On the other hand, returned host information has to be
144
* explicitly free()'d when no longer needed.
132
145
* NOTE: Returned server info is valid only until either of the two events:
133
146
* 1) SERV_GetNextInfo[Ex] is called for the same iterator again;
134
147
* 2) iterator closed (SERV_Close() called).
136
149
extern NCBI_XCONNECT_EXPORT const SSERV_Info* SERV_GetNextInfoEx
137
(SERV_ITER iter, /* handle obtained via 'SERV_Open*' call */
138
HOST_INFO* host_info /* ptr to store host info at [may be 0] */
150
(SERV_ITER iter, /* handle obtained via 'SERV_Open*' call*/
151
HOST_INFO* host_info /* ptr to store host info at [may be 0] */
142
154
extern NCBI_XCONNECT_EXPORT const SSERV_Info* SERV_GetNextInfo
147
/* This is a 'fast track' routine equivalent to creation of an iterator
159
/* This is a "fast track" routine equivalent to creation of an iterator
148
160
* as with SERV_OpenEx() and then taking an info as with SERV_GetNextInfoEx().
149
161
* However, this call is optimized for an application, which only needs
150
162
* a single entry (the first one), and which is not interested in iterating
151
* over all available entries. Both returned server info and env have to be
152
* explicitly free()'d by the application when no longer needed.
153
* Note that env is only supplied if the function returns a non-NULL result.
163
* over all available entries. Both returned server info and environment have
164
* to be explicitly free()'d by the application when no longer needed.
165
* Note that the host environment is provided only (if at all) if the function
166
* returns a non-NULL result.
155
168
extern NCBI_XCONNECT_EXPORT SSERV_Info* SERV_GetInfoEx
156
(const char* service, /* service name */
157
TSERV_Type types, /* mask of type(s) of servers requested */
158
unsigned int preferred_host,/* preferred host to use service on, nbo */
159
const SConnNetInfo* net_info, /* connection information */
160
const SSERV_Info* const skip[], /* array of servers NOT to select */
161
size_t n_skip, /* number of servers in preceding array */
162
HOST_INFO* host_info /* ptr to store host info at [may be 0] */
169
(const char* service, /* service name */
170
TSERV_Type types, /* mask of type(s) of servers requested */
171
unsigned int preferred_host,/* preferred host to use service on, nbo*/
172
const SConnNetInfo* net_info, /* connection information */
173
const SSERV_InfoCPtr skip[], /* array of servers NOT to select */
174
size_t n_skip, /* number of servers in preceding array */
175
HOST_INFO* host_info /* ptr to store host info at [may be 0] */
166
178
extern NCBI_XCONNECT_EXPORT SSERV_Info* SERV_GetInfo
167
(const char* service,
169
unsigned int preferred_host,
170
const SConnNetInfo* net_info
179
(const char* service,
181
unsigned int preferred_host,
182
const SConnNetInfo* net_info
174
/* Penalize server returned last from SERV_GetNextInfo[Ex]().
186
/* Penalize the server returned last from SERV_GetNextInfo[Ex]().
175
187
* Return 0 if failed, 1 if successful.
177
189
extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_Penalize
178
(SERV_ITER iter, /* handle obtained via 'SERV_Open*' call */
179
double fine /* fine in a range [0=min..100=max] (%%) */
190
(SERV_ITER iter, /* handle obtained via 'SERV_Open*' call*/
191
double fine /* fine in a range [0=min..100=max] (%%)*/
183
/* Reset the iterator to the state as if it'd just been opened.
184
* Caution: All previously obtained with this iterator pointers (if any)
185
* to server descriptors (SSERV_Info*) become invalid.
195
/* Reset the iterator to the state as if it has just been opened.
196
* CAUTION: All pointers to server descriptors (SSERV_Info*), if any
197
* previously obtained with this iterator, get invalidated by this call.
187
199
extern NCBI_XCONNECT_EXPORT void SERV_Reset
188
(SERV_ITER iter /* handle obtained via 'SERV_Open*' call */
200
(SERV_ITER iter /* handle obtained via 'SERV_Open*' call*/
192
/* Deallocate the iterator. Must be called to finish lookup process.
204
/* Deallocate the iterator. Must be called to finish the lookup process.
194
206
extern NCBI_XCONNECT_EXPORT void SERV_Close
195
(SERV_ITER iter /* handle obtained via 'SERV_Open*' call */
207
(SERV_ITER iter /* handle obtained via 'SERV_Open*' call*/
added
removed
connect/ncbi_service.h
