GDAL

cpl_http.h
Go to the documentation of this file.
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
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
55 CPL_C_START
56
58 typedef struct
59{ char **papszHeaders;
61 GByte *pabyData; int nDataLen;
64} CPLMimePart;
65
67 typedef struct
68{
70 int nStatus;
71
73 char *pszContentType;
74
76 char *pszErrBuf;
77
79 int nDataLen;
81 int nDataAlloc;
82
84 GByte *pabyData;
85
87 char **papszHeaders;
88
90 int nMimePartCount;
91
93 CPLMimePart *pasMimePart;
94
95} CPLHTTPResult;
96
98typedef size_t (*CPLHTTPFetchWriteFunc)(void *pBuffer, size_t nSize,
99 size_t nMemb, void *pWriteArg);
102int 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
113void CPL_DLL CPLHTTPCleanup(void);
114void CPL_DLL CPLHTTPDestroyResult(CPLHTTPResult *psResult);
115void CPL_DLL CPLHTTPDestroyMultiResult(CPLHTTPResult **papsResults, int nCount);
116int CPL_DLL CPLHTTPParseMultipartMime(CPLHTTPResult *psResult);
117
118void CPL_DLL CPLHTTPSetDefaultUserAgent(const char *pszUserAgent);
119
120/* -------------------------------------------------------------------- */
121/* To install an alternate network layer to the default Curl one */
122/* -------------------------------------------------------------------- */
141 typedef CPLHTTPResult *(*CPLHTTPFetchCallbackFunc)(
142 const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress,
143 void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg,
144 void *pUserData);
145
146void CPL_DLL CPLHTTPSetFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
147 void *pUserData);
148
149int CPL_DLL CPLHTTPPushFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
150 void *pUserData);
151int 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
161char CPL_DLL *GOA2GetAuthorizationURL(const char *pszScope);
162char CPL_DLL *GOA2GetRefreshToken(const char *pszAuthToken,
163 const char *pszScope);
164char CPL_DLL *GOA2GetAccessToken(const char *pszRefreshToken,
165 const char *pszScope);
166
167char CPL_DLL **GOA2GetAccessTokenFromServiceAccount(
168 const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope,
169 CSLConstList papszAdditionalClaims, CSLConstList papszOptions);
170
171char CPL_DLL **GOA2GetAccessTokenFromCloudEngineVM(CSLConstList papszOptions);
172
173 CPL_C_END
174
175#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
177// Not sure if this belong here, used in cpl_http.cpp, cpl_vsil_curl.cpp and
178// frmts/wms/gdalhttp.cpp
179void CPL_DLL *CPLHTTPSetOptions(void *pcurl, const char *pszURL,
180 const char *const *papszOptions);
181char **CPLHTTPGetOptionsFromEnv(const char *pszFilename);
182double CPLHTTPGetNewRetryDelay(int response_code, double dfOldDelay,
183 const char *pszErrBuf, const char *pszCurlError);
184void CPL_DLL *CPLHTTPIgnoreSigPipe();
185void CPL_DLL CPLHTTPRestoreSigPipeHandler(void *old_handler);
186bool CPLMultiPerformWait(void *hCurlMultiHandle, int &repeats);
189bool CPL_DLL CPLIsMachinePotentiallyGCEInstance();
190bool CPLIsMachineForSureGCEInstance();
191
199 class GOA2Manager
200{
201 public:
202 GOA2Manager();
203
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
225 AuthMethod GetAuthMethod() const
226 {
227 return m_eMethod;
228 }
229
230 const char *GetBearer() const;
231
233 const CPLString &GetPrivateKey() const
234 {
235 return m_osPrivateKey;
236 }
237
239 const CPLString &GetClientEmail() const
240 {
241 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 */
CPLStringList
String list class designed around our use of C "char**" string lists.
Definition: cpl_string.h:449
CPLString
Convenient string class based on std::string.
Definition: cpl_string.h:320
GOA2Manager
Manager of Google OAuth2 authentication.
Definition: cpl_http.h:200
GOA2Manager::GetClientEmail
const CPLString & GetClientEmail() const
Returns client email for SERVICE_ACCOUNT method.
Definition: cpl_http.h:239
GOA2Manager::GOA2Manager
GOA2Manager()
Constructor.
GOA2Manager::GetAuthMethod
AuthMethod GetAuthMethod() const
Returns the authentication method.
Definition: cpl_http.h:225
GOA2Manager::SetAuthFromRefreshToken
bool SetAuthFromRefreshToken(const char *pszRefreshToken, const char *pszClientId, const char *pszClientSecret, CSLConstList papszOptions)
Specifies that the authentication will be done using the OAuth2 client id method.
Definition: cpl_google_oauth2.cpp:564
GOA2Manager::SetAuthFromServiceAccount
bool SetAuthFromServiceAccount(const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope, CSLConstList papszAdditionalClaims, CSLConstList papszOptions)
Specifies that the authentication will be done using the OAuth2 service account method.
Definition: cpl_google_oauth2.cpp:599
GOA2Manager::GetPrivateKey
const CPLString & GetPrivateKey() const
Returns private key for SERVICE_ACCOUNT method.
Definition: cpl_http.h:233
GOA2Manager::GetBearer
const char * GetBearer() const
Return the access token.
Definition: cpl_google_oauth2.cpp:642
GOA2Manager::SetAuthFromGCE
bool SetAuthFromGCE(CSLConstList papszOptions)
Specifies that the authentication will be done using the local credentials of the current Google Comp...
Definition: cpl_google_oauth2.cpp:540
GOA2Manager::AuthMethod
AuthMethod
Authentication method.
Definition: cpl_http.h:206
cpl_conv.h
Various convenience functions for CPL.
CPLHTTPPopFetchCallback
int CPLHTTPPopFetchCallback(void)
Uninstalls a callback set by CPLHTTPPushFetchCallback().
Definition: cpl_http.cpp:886
CPLHTTPMultiFetch
CPLHTTPResult ** CPLHTTPMultiFetch(const char *const *papszURL, int nURLCount, int nMaxSimultaneous, CSLConstList papszOptions)
Fetch several documents at once.
Definition: cpl_http.cpp:1575
GOA2GetRefreshToken
char * GOA2GetRefreshToken(const char *pszAuthToken, const char *pszScope)
Turn Auth Token into a Refresh Token.
Definition: cpl_google_oauth2.cpp:123
CPLHTTPPushFetchCallback
int CPLHTTPPushFetchCallback(CPLHTTPFetchCallbackFunc pFunc, void *pUserData)
Installs an alternate callback to the default implementation of CPLHTTPFetchEx().
Definition: cpl_http.cpp:866
CPLHTTPCleanup
void CPLHTTPCleanup(void)
Cleanup function to call at application termination.
Definition: cpl_http.cpp:2539
GOA2GetAccessTokenFromServiceAccount
char ** GOA2GetAccessTokenFromServiceAccount(const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope, CSLConstList papszAdditionalClaims, CSLConstList papszOptions)
Fetch access token using Service Account OAuth2.
Definition: cpl_google_oauth2.cpp:426
CPLIsMachinePotentiallyGCEInstance
bool CPLIsMachinePotentiallyGCEInstance()
Returns whether the current machine is potentially a Google Compute Engine instance.
Definition: cpl_google_cloud.cpp:111
CPLHTTPFetch
CPLHTTPResult * CPLHTTPFetch(const char *pszURL, CSLConstList papszOptions)
Fetch a document from an url and return in a string.
Definition: cpl_http.cpp:1051
GOA2GetAccessTokenFromCloudEngineVM
char ** GOA2GetAccessTokenFromCloudEngineVM(CSLConstList papszOptions)
Fetch access token using Cloud Engine internal REST API.
Definition: cpl_google_oauth2.cpp:386
CPLIsMachineForSureGCEInstance
bool CPLIsMachineForSureGCEInstance()
Returns whether the current machine is surely a Google Compute Engine instance.
Definition: cpl_google_cloud.cpp:57
CPLHTTPSetFetchCallback
void CPLHTTPSetFetchCallback(CPLHTTPFetchCallbackFunc pFunc, void *pUserData)
Installs an alternate callback to the default implementation of CPLHTTPFetchEx().
Definition: cpl_http.cpp:843
CPLHTTPFetchCallbackFunc
CPLHTTPResult *(* CPLHTTPFetchCallbackFunc)(const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg, void *pUserData)
Callback function to process network requests.
Definition: cpl_http.h:141
GOA2GetAuthorizationURL
char * GOA2GetAuthorizationURL(const char *pszScope)
Return authorization url for a given scope.
Definition: cpl_google_oauth2.cpp:88
CPLHTTPFetchEx
CPLHTTPResult * CPLHTTPFetchEx(const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg)
Fetch a document from an url and return in a string.
Definition: cpl_http.cpp:1071
GOA2GetAccessToken
char * GOA2GetAccessToken(const char *pszRefreshToken, const char *pszScope)
Fetch access token using refresh token.
Definition: cpl_google_oauth2.cpp:355
CPLHTTPEnabled
int CPLHTTPEnabled(void)
Return if CPLHTTP services can be useful.
Definition: cpl_http.cpp:2522
CPLHTTPDestroyResult
void CPLHTTPDestroyResult(CPLHTTPResult *psResult)
Clean the memory associated with the return value of CPLHTTPFetch()
Definition: cpl_http.cpp:2595
CPLHTTPDestroyMultiResult
void CPLHTTPDestroyMultiResult(CPLHTTPResult **papsResults, int nCount)
Clean the memory associated with the return value of CPLHTTPMultiFetch()
Definition: cpl_http.cpp:1830
CPLHTTPSetDefaultUserAgent
void CPLHTTPSetDefaultUserAgent(const char *pszUserAgent)
Set the default user agent.
Definition: cpl_http.cpp:502
CPLHTTPParseMultipartMime
int CPLHTTPParseMultipartMime(CPLHTTPResult *psResult)
Parses a MIME multipart message.
Definition: cpl_http.cpp:2628
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:299
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:295
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition: cpl_port.h:1183
GByte
unsigned char GByte
Unsigned byte type.
Definition: cpl_port.h:185
cpl_string.h
Various convenience functions for working with strings and string lists.
cpl_vsi.h
Standard C Covers.
CPLHTTPResult
Definition: cpl_http.h:68
CPLHTTPResult::pabyData
GByte * pabyData
Definition: cpl_http.h:84
CPLHTTPResult::nStatus
int nStatus
Definition: cpl_http.h:70
CPLHTTPResult::pasMimePart
CPLMimePart * pasMimePart
Definition: cpl_http.h:93
CPLHTTPResult::pszContentType
char * pszContentType
Definition: cpl_http.h:73
CPLHTTPResult::nDataAlloc
int nDataAlloc
Definition: cpl_http.h:81
CPLHTTPResult::papszHeaders
char ** papszHeaders
Definition: cpl_http.h:87
CPLHTTPResult::pszErrBuf
char * pszErrBuf
Definition: cpl_http.h:76
CPLHTTPResult::nMimePartCount
int nMimePartCount
Definition: cpl_http.h:90
CPLHTTPResult::nDataLen
int nDataLen
Definition: cpl_http.h:79
CPLMimePart
Definition: cpl_http.h:59