ncbi_service.h
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:12k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: ncbi_service.h,v $
  4.  * PRODUCTION Revision 1000.1  2004/02/12 21:51:53  gouriano
  5.  * PRODUCTION PRODUCTION: UPGRADED [CORE_001] Dev-tree R6.32
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef CONNECT___NCBI_SERVICE__H
  10. #define CONNECT___NCBI_SERVICE__H
  11. /*  $Id: ncbi_service.h,v 1000.1 2004/02/12 21:51:53 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Anton Lavrentiev, Denis Vakatov
  37.  *
  38.  * File Description:
  39.  *   Top-level API to resolve NCBI service name to the server meta-address.
  40.  *   More elaborate documentation could be found in:
  41.  *   http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/libs/conn.html#ref_ServiceAPI
  42.  *
  43.  */
  44. #include <connect/ncbi_server_info.h>
  45. #include <connect/ncbi_host_info.h>
  46. /* Revision 6.100 */
  47. #define SERV_CLIENT_REVISION_MAJOR  6
  48. #define SERV_CLIENT_REVISION_MINOR  100
  49. /** @addtogroup ServiceSupport
  50.  *
  51.  * @{
  52.  */
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif
  56. /* Iterator through the servers
  57.  */
  58. struct SSERV_IterTag;
  59. typedef struct SSERV_IterTag* SERV_ITER;
  60. /* Create an iterator for the iterative server lookup.
  61.  * Connection information 'info' can be a NULL pointer, which means
  62.  * not to make any network connections (only LBSMD will be consulted).
  63.  * If 'info' is not NULL, LBSMD is consulted first (unless 'info->lb_disable'
  64.  * is non-zero, meaning to skip LBSMD), and then DISPD is consulted
  65.  * (using the information provided) but only if mapping with LBSMD (if any)
  66.  * has failed. This scheme permits to use any combination of service mappers.
  67.  * Note that if 'info' is not NULL then non-zero value of 'info->stateless'
  68.  * forces 'types' to have 'fSERV_StatelessOnly' set.
  69.  * NB: 'nbo' in comments denotes parameters coming in network byte order.
  70.  */
  71. /* Allocate an iterator and consult either local database (if present),
  72.  * or network database, using all default communication parameters
  73.  * found in registry and environment variables (implicit parameter
  74.  * 'info' found in two subsequent variations of this call is filled out
  75.  * internally by ConnNetInfo_Create(service) and then automatically used).
  76.  * NOTE that no preferred host (0) is set in the resultant iterator.
  77.  */
  78. extern NCBI_XCONNECT_EXPORT SERV_ITER SERV_OpenSimple
  79. (const char*         service        /* service name                          */
  80.  );
  81. /* Special values for preferred_host parameter */
  82. #define SERV_LOCALHOST  ((unsigned int)(~0UL))
  83. #define SERV_ANYHOST    0           /* default, may be used as just 0 in code*/
  84. extern NCBI_XCONNECT_EXPORT SERV_ITER SERV_OpenEx
  85. (const char*         service,       /* service name                          */
  86.  TSERV_Type          types,         /* mask of type(s) of servers requested  */
  87.  unsigned int        preferred_host,/* preferred host to use service on, nbo */
  88.  const SConnNetInfo* net_info,      /* connection information                */
  89.  const SSERV_Info*   const skip[],  /* array of servers NOT to select        */
  90.  size_t              n_skip         /* number of servers in preceding array  */
  91.  );
  92. #define SERV_Open(service, types, preferred_host, net_info) 
  93.         SERV_OpenEx(service, types, preferred_host, net_info, 0, 0)
  94. /* Get the next server meta-address, optionally accompanied by host
  95.  * environment, specified in LBSMD configuration file on that host.
  96.  * Return 0 if no more servers were found for the service requested
  97.  * (parameter 'host_info' remains untouched in this case).
  98.  * Only when completing successfully, i.e. returning non-NULL info,
  99.  * this function can also provide the host information as follows: if
  100.  * 'host_info' parameter is passed as a non-NULL pointer, then a copy of the
  101.  * host information is allocated, and pointer to it is stored in 'host_info'.
  102.  * Using this information, various host parameters like load, host
  103.  * environment, number of CPUs can be retrieved (see ncbi_host_info.h).
  104.  * NOTE:  Application program should NOT destroy returned server info:
  105.  *        it will be freed automatically upon iterator destruction.
  106.  *        On the other hand, host information has to be explicitly free()'d
  107.  *        when no longer needed.
  108.  * NOTE:  Returned server info is valid only until either of the two events:
  109.  *        1) SERV_GetNextInfo[Ex] is called for the same iterator again;
  110.  *        2) iterator closed (SERV_Close() called).
  111.  */
  112. extern NCBI_XCONNECT_EXPORT const SSERV_Info* SERV_GetNextInfoEx
  113. (SERV_ITER           iter,          /* handle obtained via 'SERV_Open*' call */
  114.  HOST_INFO*          host_info      /* ptr to store host info to [may be 0]  */
  115.  );
  116. #define SERV_GetNextInfo(iter)  SERV_GetNextInfoEx(iter, 0)
  117. /* This is a 'fast track' routine equivalent to creation of an iterator
  118.  * as with SERV_OpenEx() and then taking an info as with SERV_GetNextInfoEx().
  119.  * However, this call is optimized for an application, which only needs
  120.  * a single entry (the first one), and which is not interested in iterating
  121.  * over all available entries. Both returned server info and env have to be
  122.  * explicitly free()'d by the application when no longer needed.
  123.  * Note that env is only supplied if the function returns a non-NULL result.
  124.  */
  125. extern NCBI_XCONNECT_EXPORT SSERV_Info* SERV_GetInfoEx
  126. (const char*         service,       /* service name                          */
  127.  TSERV_Type          types,         /* mask of type(s) of servers requested  */
  128.  unsigned int        preferred_host,/* preferred host to use service on, nbo */
  129.  const SConnNetInfo* net_info,      /* connection information                */
  130.  const SSERV_Info*   const skip[],  /* array of servers NOT to select        */
  131.  size_t              n_skip,        /* number of servers in preceding array  */
  132.  HOST_INFO*          host_info      /* ptr to store host info to [may be 0]  */
  133.  );
  134. #define SERV_GetInfo(service, types, preferred_host, net_info) 
  135.     SERV_GetInfoEx(service, types, preferred_host, net_info, 0, 0, 0)
  136. /* Penalize server returned last from SERV_GetNextInfo[Ex]().
  137.  * Return 0 if failed, 1 if successful.
  138.  */
  139. extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_Penalize
  140. (SERV_ITER           iter,          /* handle obtained via 'SERV_Open*' call */
  141.  double              fine           /* fine in a range [0=min..100=max] (%%) */
  142.  );
  143. /* Reset the iterator to the state as if it'd just been opened.
  144.  * Caution: All previously obtained with this iterator pointers (if any)
  145.  * to server descriptors (SSERV_Info*) become invalid.
  146.  */
  147. extern NCBI_XCONNECT_EXPORT void SERV_Reset
  148. (SERV_ITER           iter           /* handle obtained via 'SERV_Open*' call */
  149.  );
  150. /* Deallocate the iterator. Must be called to finish lookup process.
  151.  */
  152. extern NCBI_XCONNECT_EXPORT void SERV_Close
  153. (SERV_ITER           iter           /* handle obtained via 'SERV_Open*' call */
  154.  );
  155. /* Set message hook procedure for messages originating from NCBI network
  156.  * dispatcher (if used).  Any hook will be called not more than once.
  157.  * If no hook is installed, warning message will be generated in the
  158.  * standard log file, not more than once.
  159.  */
  160. typedef void (*FDISP_MessageHook)(const char* message);
  161. extern NCBI_XCONNECT_EXPORT void DISP_SetMessageHook(FDISP_MessageHook);
  162. #ifdef __cplusplus
  163. }  /* extern "C" */
  164. #endif
  165. /* @} */
  166. /*
  167.  * --------------------------------------------------------------------------
  168.  * $Log: ncbi_service.h,v $
  169.  * Revision 1000.1  2004/02/12 21:51:53  gouriano
  170.  * PRODUCTION: UPGRADED [CORE_001] Dev-tree R6.32
  171.  *
  172.  * Revision 6.32  2004/01/30 14:37:33  lavr
  173.  * Client revision made independent of CVS revisions
  174.  *
  175.  * Revision 6.31  2003/08/11 19:05:54  lavr
  176.  * +DISP_SetMessageHook()
  177.  *
  178.  * Revision 6.30  2003/06/12 13:20:59  lavr
  179.  * Added notes for SERV_GetNextInfoEx()
  180.  *
  181.  * Revision 6.29  2003/04/09 19:05:50  siyan
  182.  * Added doxygen support
  183.  *
  184.  * Revision 6.28  2003/01/08 01:59:33  lavr
  185.  * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
  186.  *
  187.  * Revision 6.27  2002/10/28 20:12:20  lavr
  188.  * +ncbi_host_info.h
  189.  *
  190.  * Revision 6.26  2002/09/19 18:05:00  lavr
  191.  * Header file guard macro changed; log moved to end
  192.  *
  193.  * Revision 6.25  2002/05/06 19:08:35  lavr
  194.  * Removed mention of IP substitutions (mistakenly left behind a while ago)
  195.  *
  196.  * Revision 6.24  2002/04/13 06:35:10  lavr
  197.  * Fast track routine SERV_GetInfoEx(), many syscalls optimizations
  198.  *
  199.  * Revision 6.23  2001/09/26 16:55:10  lavr
  200.  * Revision log updated; in-line documentation corrected
  201.  *
  202.  * Revision 6.22  2001/09/24 20:22:59  lavr
  203.  * Added function: SERV_Reset()
  204.  *
  205.  * Revision 6.21  2001/09/10 21:18:35  lavr
  206.  * SERV_GetNextInfoEx(): Description of IP address subst in host environment
  207.  *
  208.  * Revision 6.20  2001/08/20 21:57:49  lavr
  209.  * Parameter change for clarity: info -> net_info if type is SConnNetInfo
  210.  *
  211.  * Revision 6.19  2001/07/18 17:39:56  lavr
  212.  * Comment added for SERV_OpenSimple() to note about absence of preferred host
  213.  *
  214.  * Revision 6.18  2001/06/25 15:32:06  lavr
  215.  * Added function: SERV_GetNextInfoEx()
  216.  * Both SERV_Open() and SERV_GetNextInfo() made macros for faster access
  217.  *
  218.  * Revision 6.17  2001/06/11 22:14:44  lavr
  219.  * Include files adjusted
  220.  *
  221.  * Revision 6.16  2001/06/04 17:00:10  lavr
  222.  * Include files adjusted
  223.  *
  224.  * Revision 6.15  2001/04/26 14:18:20  lavr
  225.  * SERV_MapperName() moved to a private header
  226.  *
  227.  * Revision 6.14  2001/04/24 21:15:35  lavr
  228.  * Added functions: SERV_MapperName(), SERV_Penalize()
  229.  *
  230.  * Revision 6.13  2001/03/02 20:05:56  lavr
  231.  * SERV_LOCALHOST added; SERV_OpenSimple() made more documented
  232.  *
  233.  * Revision 6.12  2001/02/09 17:32:52  lavr
  234.  * Modified: fSERV_StatelessOnly overrides info->stateless
  235.  *
  236.  * Revision 6.11  2001/01/08 22:48:00  lavr
  237.  * Double return 0 in GetNextInfo() removed:
  238.  * 0 now indicates an error unconditionally
  239.  *
  240.  * Revision 6.10  2000/12/29 17:40:30  lavr
  241.  * Pretty printed; Double 0 return added to SERV_GetNextInfo()
  242.  *
  243.  * Revision 6.9  2000/12/06 22:17:02  lavr
  244.  * Binary host addresses are now explicitly stated to be in network byte
  245.  * order, whereas binary port addresses now use native (host) representation
  246.  *
  247.  * Revision 6.8  2000/10/20 17:03:49  lavr
  248.  * Added 'const' to SConnNetInfo in SERV_OpenEx()
  249.  *
  250.  * Revision 6.7  2000/10/05 22:40:06  lavr
  251.  * Additional parameter 'info' in a call to SERV_Open()
  252.  *
  253.  * Revision 6.6  2000/10/05 21:26:30  lavr
  254.  * Log message edited
  255.  *
  256.  * Revision 6.5  2000/10/05 21:10:11  lavr
  257.  * Parameters to SERV_Open() and SERV_OpenEx() changed
  258.  *
  259.  * Revision 6.4  2000/05/31 23:12:17  lavr
  260.  * First try to assemble things together to get working service mapper
  261.  *
  262.  * Revision 6.3  2000/05/22 16:53:07  lavr
  263.  * Rename service_info -> server_info everywhere
  264.  * (including file names) as the latter name is more relevant
  265.  *
  266.  * Revision 6.2  2000/05/12 18:29:22  lavr
  267.  * First working revision
  268.  *
  269.  * ==========================================================================
  270.  */
  271. #endif /* CONNECT___NCBI_SERVICE__H */