Line data Source code
1 : /******************************************************************************
2 : * $Id$
3 : *
4 : * Project: Common Portability Library
5 : * Purpose: Function wrapper for libcurl HTTP access.
6 : * Author: Frank Warmerdam, warmerdam@pobox.com
7 : *
8 : ******************************************************************************
9 : * Copyright (c) 2006, Frank Warmerdam
10 : * Copyright (c) 2009, Even Rouault <even dot rouault at spatialys.com>
11 : *
12 : * Permission is hereby granted, free of charge, to any person obtaining a
13 : * copy of this software and associated documentation files (the "Software"),
14 : * to deal in the Software without restriction, including without limitation
15 : * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 : * and/or sell copies of the Software, and to permit persons to whom the
17 : * Software is furnished to do so, subject to the following conditions:
18 : *
19 : * The above copyright notice and this permission notice shall be included
20 : * in all copies or substantial portions of the Software.
21 : *
22 : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
23 : * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 : * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 : * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 : * DEALINGS IN THE SOFTWARE.
29 : ****************************************************************************/
30 :
31 : #ifndef CPL_HTTP_H_INCLUDED
32 : #define CPL_HTTP_H_INCLUDED
33 :
34 : #include "cpl_conv.h"
35 : #include "cpl_string.h"
36 : #include "cpl_progress.h"
37 : #include "cpl_vsi.h"
38 :
39 : /**
40 : * \file cpl_http.h
41 : *
42 : * Interface for downloading HTTP, FTP documents
43 : */
44 :
45 : /*! @cond Doxygen_Suppress */
46 : #ifndef CPL_HTTP_MAX_RETRY
47 : #define CPL_HTTP_MAX_RETRY 0
48 : #endif
49 :
50 : #ifndef CPL_HTTP_RETRY_DELAY
51 : #define CPL_HTTP_RETRY_DELAY 30.0
52 : #endif
53 : /*! @endcond */
54 :
55 : CPL_C_START
56 :
57 : /*! Describe a part of a multipart message */
58 : typedef struct
59 : {
60 : /*! NULL terminated array of headers */ char **papszHeaders;
61 :
62 : /*! Buffer with data of the part */ GByte *pabyData;
63 : /*! Buffer length */ int nDataLen;
64 : } CPLMimePart;
65 :
66 : /*! Describe the result of a CPLHTTPFetch() call */
67 : typedef struct
68 : {
69 : /*! cURL error code : 0=success, non-zero if request failed */
70 : int nStatus;
71 :
72 : /*! Content-Type of the response */
73 : char *pszContentType;
74 :
75 : /*! Error message from curl, or NULL */
76 : char *pszErrBuf;
77 :
78 : /*! Length of the pabyData buffer */
79 : int nDataLen;
80 : /*! Allocated size of the pabyData buffer */
81 : int nDataAlloc;
82 :
83 : /*! Buffer with downloaded data */
84 : GByte *pabyData;
85 :
86 : /*! Headers returned */
87 : char **papszHeaders;
88 :
89 : /*! Number of parts in a multipart message */
90 : int nMimePartCount;
91 :
92 : /*! Array of parts (resolved by CPLHTTPParseMultipartMime()) */
93 : CPLMimePart *pasMimePart;
94 :
95 : } CPLHTTPResult;
96 :
97 : /*! @cond Doxygen_Suppress */
98 : typedef size_t (*CPLHTTPFetchWriteFunc)(void *pBuffer, size_t nSize,
99 : size_t nMemb, void *pWriteArg);
100 : /*! @endcond */
101 :
102 : int CPL_DLL CPLHTTPEnabled(void);
103 : CPLHTTPResult CPL_DLL *CPLHTTPFetch(const char *pszURL,
104 : CSLConstList papszOptions);
105 : CPLHTTPResult CPL_DLL *
106 : CPLHTTPFetchEx(const char *pszURL, CSLConstList papszOptions,
107 : GDALProgressFunc pfnProgress, void *pProgressArg,
108 : CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg);
109 : CPLHTTPResult CPL_DLL **CPLHTTPMultiFetch(const char *const *papszURL,
110 : int nURLCount, int nMaxSimultaneous,
111 : CSLConstList papszOptions);
112 :
113 : void CPL_DLL CPLHTTPCleanup(void);
114 : void CPL_DLL CPLHTTPDestroyResult(CPLHTTPResult *psResult);
115 : void CPL_DLL CPLHTTPDestroyMultiResult(CPLHTTPResult **papsResults, int nCount);
116 : int CPL_DLL CPLHTTPParseMultipartMime(CPLHTTPResult *psResult);
117 :
118 : void CPL_DLL CPLHTTPSetDefaultUserAgent(const char *pszUserAgent);
119 :
120 : /* -------------------------------------------------------------------- */
121 : /* To install an alternate network layer to the default Curl one */
122 : /* -------------------------------------------------------------------- */
123 : /** Callback function to process network requests.
124 : *
125 : * If CLOSE_PERSISTENT is found in papszOptions, no network request should be
126 : * issued, but a dummy non-null CPLHTTPResult* should be returned by the
127 : * callback.
128 : *
129 : * Its first arguments are the same as CPLHTTPFetchEx()
130 : * @param pszURL See CPLHTTPFetchEx()
131 : * @param papszOptions See CPLHTTPFetchEx()
132 : * @param pfnProgress See CPLHTTPFetchEx()
133 : * @param pProgressArg See CPLHTTPFetchEx()
134 : * @param pfnWrite See CPLHTTPFetchEx()
135 : * @param pWriteArg See CPLHTTPFetchEx()
136 : * @param pUserData user data value that was passed during
137 : * CPLHTTPPushFetchCallback()
138 : * @return nullptr if the request cannot be processed, in which case the
139 : * previous handler will be used.
140 : */
141 : typedef CPLHTTPResult *(*CPLHTTPFetchCallbackFunc)(
142 : const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress,
143 : void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg,
144 : void *pUserData);
145 :
146 : void CPL_DLL CPLHTTPSetFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
147 : void *pUserData);
148 :
149 : int CPL_DLL CPLHTTPPushFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
150 : void *pUserData);
151 : int CPL_DLL CPLHTTPPopFetchCallback(void);
152 :
153 : /* -------------------------------------------------------------------- */
154 : /* The following is related to OAuth2 authorization around */
155 : /* google services like fusion tables, and potentially others */
156 : /* in the future. Code in cpl_google_oauth2.cpp. */
157 : /* */
158 : /* These services are built on CPL HTTP services. */
159 : /* -------------------------------------------------------------------- */
160 :
161 : char CPL_DLL *GOA2GetAuthorizationURL(const char *pszScope);
162 : char CPL_DLL *GOA2GetRefreshToken(const char *pszAuthToken,
163 : const char *pszScope);
164 : char CPL_DLL *GOA2GetAccessToken(const char *pszRefreshToken,
165 : const char *pszScope);
166 :
167 : char CPL_DLL **GOA2GetAccessTokenFromServiceAccount(
168 : const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope,
169 : CSLConstList papszAdditionalClaims, CSLConstList papszOptions);
170 :
171 : char CPL_DLL **GOA2GetAccessTokenFromCloudEngineVM(CSLConstList papszOptions);
172 :
173 : CPL_C_END
174 :
175 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
176 : /*! @cond Doxygen_Suppress */
177 : // Not sure if this belong here, used in cpl_http.cpp, cpl_vsil_curl.cpp and
178 : // frmts/wms/gdalhttp.cpp
179 : void CPL_DLL *CPLHTTPSetOptions(void *pcurl, const char *pszURL,
180 : const char *const *papszOptions);
181 : char **CPLHTTPGetOptionsFromEnv(const char *pszFilename);
182 : double CPLHTTPGetNewRetryDelay(int response_code, double dfOldDelay,
183 : const char *pszErrBuf, const char *pszCurlError);
184 : void CPL_DLL *CPLHTTPIgnoreSigPipe();
185 : void CPL_DLL CPLHTTPRestoreSigPipeHandler(void *old_handler);
186 : bool CPLMultiPerformWait(void *hCurlMultiHandle, int &repeats);
187 : /*! @endcond */
188 :
189 : bool CPL_DLL CPLIsMachinePotentiallyGCEInstance();
190 : bool CPLIsMachineForSureGCEInstance();
191 :
192 : /** Manager of Google OAuth2 authentication.
193 : *
194 : * This class handles different authentication methods and handles renewal
195 : * of access token.
196 : *
197 : * @since GDAL 2.3
198 : */
199 1553 : class GOA2Manager
200 : {
201 : public:
202 : GOA2Manager();
203 :
204 : /** Authentication method */
205 : typedef enum
206 : {
207 : NONE,
208 : GCE,
209 : ACCESS_TOKEN_FROM_REFRESH,
210 : SERVICE_ACCOUNT
211 : } AuthMethod;
212 :
213 : bool SetAuthFromGCE(CSLConstList papszOptions);
214 : bool SetAuthFromRefreshToken(const char *pszRefreshToken,
215 : const char *pszClientId,
216 : const char *pszClientSecret,
217 : CSLConstList papszOptions);
218 : bool SetAuthFromServiceAccount(const char *pszPrivateKey,
219 : const char *pszClientEmail,
220 : const char *pszScope,
221 : CSLConstList papszAdditionalClaims,
222 : CSLConstList papszOptions);
223 :
224 : /** Returns the authentication method. */
225 64 : AuthMethod GetAuthMethod() const
226 : {
227 64 : return m_eMethod;
228 : }
229 :
230 : const char *GetBearer() const;
231 :
232 : /** Returns private key for SERVICE_ACCOUNT method */
233 1 : const CPLString &GetPrivateKey() const
234 : {
235 1 : return m_osPrivateKey;
236 : }
237 :
238 : /** Returns client email for SERVICE_ACCOUNT method */
239 1 : const CPLString &GetClientEmail() const
240 : {
241 1 : return m_osClientEmail;
242 : }
243 :
244 : private:
245 : mutable CPLString m_osCurrentBearer{};
246 : mutable time_t m_nExpirationTime = 0;
247 : AuthMethod m_eMethod = NONE;
248 :
249 : // for ACCESS_TOKEN_FROM_REFRESH
250 : CPLString m_osClientId{};
251 : CPLString m_osClientSecret{};
252 : CPLString m_osRefreshToken{};
253 :
254 : // for SERVICE_ACCOUNT
255 : CPLString m_osPrivateKey{};
256 : CPLString m_osClientEmail{};
257 : CPLString m_osScope{};
258 : CPLStringList m_aosAdditionalClaims{};
259 :
260 : CPLStringList m_aosOptions{};
261 : };
262 :
263 : #endif // __cplusplus
264 :
265 : #endif /* ndef CPL_HTTP_H_INCLUDED */
|
