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 mines-paris dot org>
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 #define CPL_HTTP_MAX_RETRY 0
47 #define CPL_HTTP_RETRY_DELAY 30.0
48 
51 
53 typedef struct { char **papszHeaders;
55  GByte *pabyData; int nDataLen;
58 } CPLMimePart;
59 
61 typedef struct {
63  int nStatus;
64 
67 
69  char *pszErrBuf;
70 
72  int nDataLen;
75 
78 
80  char **papszHeaders;
81 
84 
87 
89 
91 typedef size_t (*CPLHTTPFetchWriteFunc)(void *pBuffer, size_t nSize, size_t nMemb, void *pWriteArg);
94 int CPL_DLL CPLHTTPEnabled( void );
95 CPLHTTPResult CPL_DLL *CPLHTTPFetch( const char *pszURL, CSLConstList papszOptions);
96 CPLHTTPResult CPL_DLL *CPLHTTPFetchEx( const char *pszURL,CSLConstList papszOptions,
97  GDALProgressFunc pfnProgress,
98  void *pProgressArg,
99  CPLHTTPFetchWriteFunc pfnWrite,
100  void *pWriteArg);
101 CPLHTTPResult CPL_DLL **CPLHTTPMultiFetch( const char * const * papszURL,
102  int nURLCount,
103  int nMaxSimultaneous,
104  CSLConstList papszOptions);
105 
106 void CPL_DLL CPLHTTPCleanup( void );
107 void CPL_DLL CPLHTTPDestroyResult( CPLHTTPResult *psResult );
108 void CPL_DLL CPLHTTPDestroyMultiResult( CPLHTTPResult **papsResults, int nCount );
109 int CPL_DLL CPLHTTPParseMultipartMime( CPLHTTPResult *psResult );
110 
111 /* -------------------------------------------------------------------- */
112 /* The following is related to OAuth2 authorization around */
113 /* google services like fusion tables, and potentially others */
114 /* in the future. Code in cpl_google_oauth2.cpp. */
115 /* */
116 /* These services are built on CPL HTTP services. */
117 /* -------------------------------------------------------------------- */
118 
119 char CPL_DLL *GOA2GetAuthorizationURL( const char *pszScope );
120 char CPL_DLL *GOA2GetRefreshToken( const char *pszAuthToken,
121  const char *pszScope );
122 char CPL_DLL *GOA2GetAccessToken( const char *pszRefreshToken,
123  const char *pszScope );
124 
126  const char* pszPrivateKey,
127  const char* pszClientEmail,
128  const char* pszScope,
129  CSLConstList papszAdditionalClaims,
130  CSLConstList papszOptions);
131 
132 char CPL_DLL **GOA2GetAccessTokenFromCloudEngineVM( CSLConstList papszOptions );
133 
134 CPL_C_END
135 
136 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
137 
138 // Not sure if this belong here, used in cpl_http.cpp, cpl_vsil_curl.cpp and frmts/wms/gdalhttp.cpp
139 void* CPLHTTPSetOptions(void *pcurl, const char * const* papszOptions);
140 char** CPLHTTPGetOptionsFromEnv();
141 double CPLHTTPGetNewRetryDelay(int response_code, double dfOldDelay);
142 void* CPLHTTPIgnoreSigPipe();
143 void CPLHTTPRestoreSigPipeHandler(void* old_handler);
144 bool CPLMultiPerformWait(void* hCurlMultiHandle, int& repeats);
149 
158 {
159  public:
160 
161  GOA2Manager();
162 
164  typedef enum
165  {
166  NONE,
167  GCE,
168  ACCESS_TOKEN_FROM_REFRESH,
169  SERVICE_ACCOUNT
170  } AuthMethod;
171 
172  bool SetAuthFromGCE( CSLConstList papszOptions );
173  bool SetAuthFromRefreshToken( const char* pszRefreshToken,
174  const char* pszClientId,
175  const char* pszClientSecret,
176  CSLConstList papszOptions );
177  bool SetAuthFromServiceAccount(const char* pszPrivateKey,
178  const char* pszClientEmail,
179  const char* pszScope,
180  CSLConstList papszAdditionalClaims,
181  CSLConstList papszOptions );
182 
184  AuthMethod GetAuthMethod() const { return m_eMethod; }
185 
186  const char* GetBearer() const;
187 
189  const CPLString& GetPrivateKey() const { return m_osPrivateKey; }
190 
192  const CPLString& GetClientEmail() const { return m_osClientEmail; }
193 
194  private:
195 
196  mutable CPLString m_osCurrentBearer{};
197  mutable time_t m_nExpirationTime = 0;
198  AuthMethod m_eMethod = NONE;
199 
200  // for ACCESS_TOKEN_FROM_REFRESH
201  CPLString m_osClientId{};
202  CPLString m_osClientSecret{};
203  CPLString m_osRefreshToken{};
204 
205  // for SERVICE_ACCOUNT
206  CPLString m_osPrivateKey{};
207  CPLString m_osClientEmail{};
208  CPLString m_osScope{};
209  CPLStringList m_aosAdditionalClaims{};
210 
211  CPLStringList m_aosOptions{};
212 };
213 
214 
215 #endif // __cplusplus
216 
217 #endif /* ndef CPL_HTTP_H_INCLUDED */
CPLMimePart * pasMimePart
Definition: cpl_http.h:86
const CPLString & GetClientEmail() const
Returns client email for SERVICE_ACCOUNT method.
Definition: cpl_http.h:192
Standard C Covers.
CPLHTTPResult * CPLHTTPFetch(const char *pszURL, CSLConstList papszOptions)
Fetch a document from an url and return in a string.
Definition: cpl_http.cpp:620
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:335
bool CPLIsMachineForSureGCEInstance()
Returns whether the current machine is surely a Google Compute Engine instance.
Definition: cpl_google_cloud.cpp:58
void CPLHTTPCleanup(void)
Cleanup function to call at application termination.
Definition: cpl_http.cpp:1870
char * pszContentType
Definition: cpl_http.h:66
const CPLString & GetPrivateKey() const
Returns private key for SERVICE_ACCOUNT method.
Definition: cpl_http.h:189
int CPLHTTPParseMultipartMime(CPLHTTPResult *psResult)
Parses a MIME multipart message.
Definition: cpl_http.cpp:1965
void CPLHTTPDestroyResult(CPLHTTPResult *psResult)
Clean the memory associated with the return value of CPLHTTPFetch()
Definition: cpl_http.cpp:1932
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:636
unsigned char GByte
Unsigned byte type.
Definition: cpl_port.h:213
char ** papszHeaders
Definition: cpl_http.h:80
const char * GetBearer() const
Return the access token.
Definition: cpl_google_oauth2.cpp:677
Convenient string class based on std::string.
Definition: cpl_string.h:327
char ** GOA2GetAccessTokenFromCloudEngineVM(CSLConstList papszOptions)
Fetch access token using Cloud Engine internal REST API.
Definition: cpl_google_oauth2.cpp:418
CPLHTTPResult ** CPLHTTPMultiFetch(const char *const *papszURL, int nURLCount, int nMaxSimultaneous, CSLConstList papszOptions)
Fetch several documents at once.
Definition: cpl_http.cpp:1102
char * GOA2GetAccessToken(const char *pszRefreshToken, const char *pszScope)
Fetch access token using refresh token.
Definition: cpl_google_oauth2.cpp:387
Various convenience functions for working with strings and string lists.
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:595
AuthMethod GetAuthMethod() const
Returns the authentication method.
Definition: cpl_http.h:184
int CPLHTTPEnabled(void)
Return if CPLHTTP services can be useful.
Definition: cpl_http.cpp:1853
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:570
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition: cpl_port.h:1184
int nMimePartCount
Definition: cpl_http.h:83
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:631
void CPLHTTPDestroyMultiResult(CPLHTTPResult **papsResults, int nCount)
Clean the memory associated with the return value of CPLHTTPMultiFetch()
Definition: cpl_http.cpp:1350
String list class designed around our use of C "char**" string lists.
Definition: cpl_string.h:435
int nDataAlloc
Definition: cpl_http.h:74
int nDataLen
Definition: cpl_http.h:72
Various convenience functions for CPL.
AuthMethod
Authentication method.
Definition: cpl_http.h:164
bool CPLIsMachinePotentiallyGCEInstance()
Returns whether the current machine is potentially a Google Compute Engine instance.
Definition: cpl_google_cloud.cpp:120
Definition: cpl_http.h:61
int nStatus
Definition: cpl_http.h:63
Manager of Google OAuth2 authentication.
Definition: cpl_http.h:157
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:459
GByte * pabyData
Definition: cpl_http.h:77
Definition: cpl_http.h:53
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:337
char * pszErrBuf
Definition: cpl_http.h:69
char * GOA2GetRefreshToken(const char *pszAuthToken, const char *pszScope)
Turn Auth Token into a Refresh Token.
Definition: cpl_google_oauth2.cpp:164
char * GOA2GetAuthorizationURL(const char *pszScope)
Return authorization url for a given scope.
Definition: cpl_google_oauth2.cpp:127
GOA2Manager()
Constructor.

Generated for GDAL by doxygen 1.8.8.