NCBI C++ ToolKit
ncbi_localnet.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT_EXT___NCBI_LOCALNET__H
2 #define CONNECT_EXT___NCBI_LOCALNET__H
3 
4 /* $Id: ncbi_localnet.h 99864 2023-05-17 19:32:48Z saprykin $
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: Anton Lavrentiev
30  *
31  * File Description:
32  * Get IP address of a CGI client and determine the IP locality
33  *
34  * NOTE: This is an internal NCBI-only API not for export to third parties.
35  *
36  */
37 
38 #include <connect/ncbi_ipv6.h>
39 #include <connect/ncbi_localip.h> /* for backward-compatibility */
40 
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 
47 /**
48  * Return non-zero (true) if called from within a CGI that was invoked by an
49  * NCBI local client; zero otherwise.
50  *
51  * @param tracking_env
52  * string array with the tracking environment, or if NULL then the process
53  * environment (as provided by the run-time library) is used
54  */
55 extern int/*bool*/ NcbiIsLocalCgiClient
56 (const char* const* tracking_env);
57 
58 
59 /**
60  * Return non-zero (true) if the IP address (in network byte order) provided as
61  * an agrument, is a nonroutable private IP address (including loopback,
62  * multicast, and RFC1918); return zero (false) otherwise.
63  */
64 extern int/*bool*/ NcbiIsPrivateIP
65 (unsigned int ip);
66 
67 
68 /**
69  * Return non-zero (true) if the IP address (in network byte order) provided as
70  * an agrument, is an Automatic Private IP Address (APIPA); return zero (false)
71  * otherwise.
72  */
73 extern int/*bool*/ NcbiIsAPIPA
74 (unsigned int ip);
75 
76 
77 /**
78  * Return IP address (in network byte order) of the CGI client, and optionally
79  * store the client hostname in a user-supplied buffer (if the size is not
80  * adequate to accomodate the result, then it is not stored).
81  * Return 0 if the IP address cannot be obtained; however, the text form of
82  * the host can still be stored in the provided buffer (check for '\0' at [0]).
83  * @warning
84  * Result is generally undefined if called not from within a CGI executable.
85  *
86  * @param flag
87  * modifies the search algorithm: most users would want to specify
88  * eCgiClientIP_TryAll (and those who are absolutely sure that the requests
89  * cannot be coming from the older NI facility of the C Toolkit, would want
90  * to use eCgiClientIP_TryMost); eCgiClientIP_TryLeast causes the search
91  * to ignore the special "Client-Host:" tag that can indicate the real origin
92  * of the request (when this request is made on behalf of the indicated IP)
93  * @param buf
94  * buffer where the client host (a hostname or textual representation of the
95  * network address as provided by the web-server) will be saved (may be NULL
96  * not to save)
97  * @param buf_size
98  * the size of the buffer (must be large enough, truncation not allowed)
99  * @param tracking_env
100  * string array with the tracking environment, or if NULL then the process
101  * environment (as provided by the run-time library) is used
102  * @warning
103  * FCGI applications *must* use CCgiRequest::GetClientTrackingEnv() to obtain
104  * proper tracking environment per each request
105  * @sa
106  * CCgiRequest::GetClientTrackingEnv()
107  */
108 
109 typedef enum {
110  eCgiClientIP_TryAll = 0, /**< Try all env.vars (NI_CLIENT_IPADDR incl.)*/
111  eCgiClientIP_TryMost = 1, /**< Try most of known environment variables */
112  eCgiClientIP_TryLeast = 2 /**< Try to detect caller's IP only,not origin*/
114 
115 extern unsigned int NcbiGetCgiClientIPEx
116 (ECgiClientIP flag,
117  char* buf,
118  size_t buf_size,
119  const char* const* tracking_env
120  );
121 
122 /** Same as NcbiGetCgiClientIPEx(., NULL, 0, .)
123  * @sa
124  * NcbiGetCgiClientIPEx
125  */
126 extern unsigned int NcbiGetCgiClientIP
127 (ECgiClientIP flag,
128  const char* const* tracking_env
129  );
130 
131 
132 /**
133  * Same as NcbiGetCgiClientIPEx but IPv6-aware. IPv4 addresses packed as IPv6.
134  * Returns an empty IPv6 address when NcbiGetCgiClientIPEx() would return 0.
135  * @sa
136  * NcbiGetCgiClientIPEx
137  */
139 (ECgiClientIP flag,
140  char* buf,
141  size_t buf_size,
142  const char* const* tracking_env
143  );
144 
145 /** Same as NcbiGetCgiClientIPv6Ex(., NULL, 0, .)
146  * @sa
147  * NcbiGetCgiClientIPv6Ex
148  */
150 (ECgiClientIP flag,
151  const char* const* tracking_env
152  );
153 
154 
155 #ifdef __cplusplus
156 } /* extern "C" */
157 #endif
158 
159 
160 #endif /*CONNECT_EXT___NCBI_LOCALNET__H*/
static const char ip[]
Definition: des.c:75
char * buf
TNCBI_IPv6Addr NcbiGetCgiClientIPv6Ex(ECgiClientIP flag, char *buf, size_t buf_size, const char *const *tracking_env)
Same as NcbiGetCgiClientIPEx but IPv6-aware.
int NcbiIsLocalCgiClient(const char *const *tracking_env)
Return non-zero (true) if called from within a CGI that was invoked by an NCBI local client; zero oth...
int NcbiIsAPIPA(unsigned int ip)
Return non-zero (true) if the IP address (in network byte order) provided as an agrument,...
unsigned int NcbiGetCgiClientIPEx(ECgiClientIP flag, char *buf, size_t buf_size, const char *const *tracking_env)
unsigned int NcbiGetCgiClientIP(ECgiClientIP flag, const char *const *tracking_env)
Same as NcbiGetCgiClientIPEx(., NULL, 0, .)
TNCBI_IPv6Addr NcbiGetCgiClientIPv6(ECgiClientIP flag, const char *const *tracking_env)
Same as NcbiGetCgiClientIPv6Ex(., NULL, 0, .)
ECgiClientIP
Return IP address (in network byte order) of the CGI client, and optionally store the client hostname...
@ eCgiClientIP_TryLeast
Try to detect caller's IP only,not origin.
@ eCgiClientIP_TryMost
Try most of known environment variables.
@ eCgiClientIP_TryAll
Try all env.vars (NI_CLIENT_IPADDR incl.)
int NcbiIsPrivateIP(unsigned int ip)
Return non-zero (true) if the IP address (in network byte order) provided as an agrument,...
Definition: ncbi_localnet.c:89
Modified on Wed Apr 17 13:10:44 2024 by modify_doxy.py rev. 669887