1 /****************************************************************************** 2 * $Id: cpl_http.h 5bf28e3bebd1032c4c8f50564d077f95cdf897d3 2020-09-30 14:07:46 +0200 Even Rouault $ 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 /*! NULL terminated array of headers */ char **papszHeaders; 60 61 /*! Buffer with data of the part */ GByte *pabyData; 62 /*! Buffer length */ int nDataLen; 63 } CPLMimePart; 64 65 /*! Describe the result of a CPLHTTPFetch() call */ 66 typedef struct { 67 /*! cURL error code : 0=success, non-zero if request failed */ 68 int nStatus; 69 70 /*! Content-Type of the response */ 71 char *pszContentType; 72 73 /*! Error message from curl, or NULL */ 74 char *pszErrBuf; 75 76 /*! Length of the pabyData buffer */ 77 int nDataLen; 78 /*! Allocated size of the pabyData buffer */ 79 int nDataAlloc; 80 81 /*! Buffer with downloaded data */ 82 GByte *pabyData; 83 84 /*! Headers returned */ 85 char **papszHeaders; 86 87 /*! Number of parts in a multipart message */ 88 int nMimePartCount; 89 90 /*! Array of parts (resolved by CPLHTTPParseMultipartMime()) */ 91 CPLMimePart *pasMimePart; 92 93 } CPLHTTPResult; 94 95 /*! @cond Doxygen_Suppress */ 96 typedef size_t (*CPLHTTPFetchWriteFunc)(void *pBuffer, size_t nSize, size_t nMemb, void *pWriteArg); 97 /*! @endcond */ 98 99 int CPL_DLL CPLHTTPEnabled( void ); 100 CPLHTTPResult CPL_DLL *CPLHTTPFetch( const char *pszURL, CSLConstList papszOptions); 101 CPLHTTPResult CPL_DLL *CPLHTTPFetchEx( const char *pszURL,CSLConstList papszOptions, 102 GDALProgressFunc pfnProgress, 103 void *pProgressArg, 104 CPLHTTPFetchWriteFunc pfnWrite, 105 void *pWriteArg); 106 CPLHTTPResult CPL_DLL **CPLHTTPMultiFetch( const char * const * papszURL, 107 int nURLCount, 108 int nMaxSimultaneous, 109 CSLConstList papszOptions); 110 111 void CPL_DLL CPLHTTPCleanup( void ); 112 void CPL_DLL CPLHTTPDestroyResult( CPLHTTPResult *psResult ); 113 void CPL_DLL CPLHTTPDestroyMultiResult( CPLHTTPResult **papsResults, int nCount ); 114 int CPL_DLL CPLHTTPParseMultipartMime( CPLHTTPResult *psResult ); 115 116 /* -------------------------------------------------------------------- */ 117 /* To install an alternate network layer to the default Curl one */ 118 /* -------------------------------------------------------------------- */ 119 /** Callback function to process network requests. 120 * 121 * If CLOSE_PERSISTENT is found in papszOptions, no network request should be 122 * issued, but a dummy non-null CPLHTTPResult* should be returned by the callback. 123 * 124 * Its first arguments are the same as CPLHTTPFetchEx() 125 * @param pszURL See CPLHTTPFetchEx() 126 * @param papszOptions See CPLHTTPFetchEx() 127 * @param pfnProgress See CPLHTTPFetchEx() 128 * @param pProgressArg See CPLHTTPFetchEx() 129 * @param pfnWrite See CPLHTTPFetchEx() 130 * @param pWriteArg See CPLHTTPFetchEx() 131 * @param pUserData user data value that was passed during CPLHTTPPushFetchCallback() 132 * @return nullptr if the request cannot be processed, in which case the previous handler will be used. 133 */ 134 typedef CPLHTTPResult* (*CPLHTTPFetchCallbackFunc)( const char *pszURL, 135 CSLConstList papszOptions, 136 GDALProgressFunc pfnProgress, 137 void *pProgressArg, 138 CPLHTTPFetchWriteFunc pfnWrite, 139 void *pWriteArg, 140 void* pUserData ); 141 142 void CPL_DLL CPLHTTPSetFetchCallback( CPLHTTPFetchCallbackFunc pFunc, 143 void* pUserData ); 144 145 int CPL_DLL CPLHTTPPushFetchCallback( CPLHTTPFetchCallbackFunc pFunc, 146 void* pUserData ); 147 int CPL_DLL CPLHTTPPopFetchCallback(void); 148 149 /* -------------------------------------------------------------------- */ 150 /* The following is related to OAuth2 authorization around */ 151 /* google services like fusion tables, and potentially others */ 152 /* in the future. Code in cpl_google_oauth2.cpp. */ 153 /* */ 154 /* These services are built on CPL HTTP services. */ 155 /* -------------------------------------------------------------------- */ 156 157 char CPL_DLL *GOA2GetAuthorizationURL( const char *pszScope ); 158 char CPL_DLL *GOA2GetRefreshToken( const char *pszAuthToken, 159 const char *pszScope ); 160 char CPL_DLL *GOA2GetAccessToken( const char *pszRefreshToken, 161 const char *pszScope ); 162 163 char CPL_DLL **GOA2GetAccessTokenFromServiceAccount( 164 const char* pszPrivateKey, 165 const char* pszClientEmail, 166 const char* pszScope, 167 CSLConstList papszAdditionalClaims, 168 CSLConstList papszOptions); 169 170 char CPL_DLL **GOA2GetAccessTokenFromCloudEngineVM( CSLConstList papszOptions ); 171 172 CPL_C_END 173 174 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS) 175 /*! @cond Doxygen_Suppress */ 176 // Not sure if this belong here, used in cpl_http.cpp, cpl_vsil_curl.cpp and frmts/wms/gdalhttp.cpp 177 void* CPLHTTPSetOptions(void *pcurl, const char *pszURL, const char * const* papszOptions); 178 char** CPLHTTPGetOptionsFromEnv(); 179 double CPLHTTPGetNewRetryDelay(int response_code, double dfOldDelay, 180 const char* pszErrBuf, const char* pszCurlError); 181 void* CPLHTTPIgnoreSigPipe(); 182 void CPLHTTPRestoreSigPipeHandler(void* old_handler); 183 bool CPLMultiPerformWait(void* hCurlMultiHandle, int& repeats); 184 /*! @endcond */ 185 186 bool CPLIsMachinePotentiallyGCEInstance(); 187 bool CPLIsMachineForSureGCEInstance(); 188 189 /** Manager of Google OAuth2 authentication. 190 * 191 * This class handles different authentication methods and handles renewal 192 * of access token. 193 * 194 * @since GDAL 2.3 195 */ 196 class GOA2Manager 197 { 198 public: 199 200 GOA2Manager(); 201 202 /** Authentication method */ 203 typedef enum 204 { 205 NONE, 206 GCE, 207 ACCESS_TOKEN_FROM_REFRESH, 208 SERVICE_ACCOUNT 209 } AuthMethod; 210 211 bool SetAuthFromGCE( CSLConstList papszOptions ); 212 bool SetAuthFromRefreshToken( const char* pszRefreshToken, 213 const char* pszClientId, 214 const char* pszClientSecret, 215 CSLConstList papszOptions ); 216 bool SetAuthFromServiceAccount(const char* pszPrivateKey, 217 const char* pszClientEmail, 218 const char* pszScope, 219 CSLConstList papszAdditionalClaims, 220 CSLConstList papszOptions ); 221 222 /** Returns the authentication method. */ GetAuthMethod()223 AuthMethod GetAuthMethod() const { return m_eMethod; } 224 225 const char* GetBearer() const; 226 227 /** Returns private key for SERVICE_ACCOUNT method */ GetPrivateKey()228 const CPLString& GetPrivateKey() const { return m_osPrivateKey; } 229 230 /** Returns client email for SERVICE_ACCOUNT method */ GetClientEmail()231 const CPLString& GetClientEmail() const { return m_osClientEmail; } 232 233 private: 234 235 mutable CPLString m_osCurrentBearer{}; 236 mutable time_t m_nExpirationTime = 0; 237 AuthMethod m_eMethod = NONE; 238 239 // for ACCESS_TOKEN_FROM_REFRESH 240 CPLString m_osClientId{}; 241 CPLString m_osClientSecret{}; 242 CPLString m_osRefreshToken{}; 243 244 // for SERVICE_ACCOUNT 245 CPLString m_osPrivateKey{}; 246 CPLString m_osClientEmail{}; 247 CPLString m_osScope{}; 248 CPLStringList m_aosAdditionalClaims{}; 249 250 CPLStringList m_aosOptions{}; 251 }; 252 253 254 #endif // __cplusplus 255 256 #endif /* ndef CPL_HTTP_H_INCLUDED */ 257