GDAL
|
Interface for downloading HTTP, FTP documents. More...
Go to the source code of this file.
Classes | |
struct | CPLMimePart |
struct | CPLHTTPResult |
class | GOA2Manager |
Manager of Google OAuth2 authentication. More... | |
Typedefs | |
typedef CPLHTTPResult *(* | CPLHTTPFetchCallbackFunc) (const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg, void *pUserData) |
Callback function to process network requests. More... | |
Functions | |
int | CPLHTTPEnabled (void) |
Return if CPLHTTP services can be useful. More... | |
CPLHTTPResult * | CPLHTTPFetch (const char *pszURL, CSLConstList papszOptions) |
Fetch a document from an url and return in a string. More... | |
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. More... | |
CPLHTTPResult ** | CPLHTTPMultiFetch (const char *const *papszURL, int nURLCount, int nMaxSimultaneous, CSLConstList papszOptions) |
Fetch several documents at once. More... | |
void | CPLHTTPCleanup (void) |
Cleanup function to call at application termination. | |
void | CPLHTTPDestroyResult (CPLHTTPResult *psResult) |
Clean the memory associated with the return value of CPLHTTPFetch() More... | |
void | CPLHTTPDestroyMultiResult (CPLHTTPResult **papsResults, int nCount) |
Clean the memory associated with the return value of CPLHTTPMultiFetch() More... | |
int | CPLHTTPParseMultipartMime (CPLHTTPResult *psResult) |
Parses a MIME multipart message. More... | |
void | CPLHTTPSetDefaultUserAgent (const char *pszUserAgent) |
Set the default user agent. More... | |
void | CPLHTTPSetFetchCallback (CPLHTTPFetchCallbackFunc pFunc, void *pUserData) |
Installs an alternate callback to the default implementation of CPLHTTPFetchEx(). More... | |
int | CPLHTTPPushFetchCallback (CPLHTTPFetchCallbackFunc pFunc, void *pUserData) |
Installs an alternate callback to the default implementation of CPLHTTPFetchEx(). More... | |
int | CPLHTTPPopFetchCallback (void) |
Uninstalls a callback set by CPLHTTPPushFetchCallback(). More... | |
char * | GOA2GetAuthorizationURL (const char *pszScope) |
Return authorization url for a given scope. More... | |
char * | GOA2GetRefreshToken (const char *pszAuthToken, const char *pszScope) |
Turn Auth Token into a Refresh Token. More... | |
char * | GOA2GetAccessToken (const char *pszRefreshToken, const char *pszScope) |
Fetch access token using refresh token. More... | |
char ** | GOA2GetAccessTokenFromServiceAccount (const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope, CSLConstList papszAdditionalClaims, CSLConstList papszOptions) |
Fetch access token using Service Account OAuth2. More... | |
char ** | GOA2GetAccessTokenFromCloudEngineVM (CSLConstList papszOptions) |
Fetch access token using Cloud Engine internal REST API. More... | |
bool | CPLIsMachinePotentiallyGCEInstance () |
Returns whether the current machine is potentially a Google Compute Engine instance. More... | |
bool | CPLIsMachineForSureGCEInstance () |
Returns whether the current machine is surely a Google Compute Engine instance. More... | |
Interface for downloading HTTP, FTP documents.
typedef CPLHTTPResult*(* CPLHTTPFetchCallbackFunc) (const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg, void *pUserData) |
Callback function to process network requests.
If CLOSE_PERSISTENT is found in papszOptions, no network request should be issued, but a dummy non-null CPLHTTPResult* should be returned by the callback.
Its first arguments are the same as CPLHTTPFetchEx()
pszURL | See CPLHTTPFetchEx() |
papszOptions | See CPLHTTPFetchEx() |
pfnProgress | See CPLHTTPFetchEx() |
pProgressArg | See CPLHTTPFetchEx() |
pfnWrite | See CPLHTTPFetchEx() |
pWriteArg | See CPLHTTPFetchEx() |
pUserData | user data value that was passed during CPLHTTPPushFetchCallback() |
void CPLHTTPDestroyMultiResult | ( | CPLHTTPResult ** | papsResults, |
int | nCount | ||
) |
Clean the memory associated with the return value of CPLHTTPMultiFetch()
papsResults | pointer to the return value of CPLHTTPMultiFetch() |
nCount | value of the nURLCount parameter passed to CPLHTTPMultiFetch() |
void CPLHTTPDestroyResult | ( | CPLHTTPResult * | psResult | ) |
Clean the memory associated with the return value of CPLHTTPFetch()
psResult | pointer to the return value of CPLHTTPFetch() |
int CPLHTTPEnabled | ( | void | ) |
Return if CPLHTTP services can be useful.
Those services depend on GDAL being build with libcurl support.
CPLHTTPResult* CPLHTTPFetch | ( | const char * | pszURL, |
CSLConstList | papszOptions | ||
) |
Fetch a document from an url and return in a string.
Different options may be passed through the papszOptions function parameter, or for most of them through a configuration option:
If an option is specified through papszOptions and as a configuration option, the former takes precedence over the later.
Starting with GDAL 3.7, the above configuration options can also be specified as path-specific options with VSISetPathSpecificOption().
pszURL | valid URL recognized by underlying download library (libcurl) |
papszOptions | option list as a NULL-terminated array of strings. May be NULL. |
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.
pszURL | Url to fetch document from web. |
papszOptions | Option list as a NULL-terminated array of strings. Available keys see in CPLHTTPFetch. |
pfnProgress | Callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL. |
pProgressArg | Callback argument passed to pfnProgress. |
pfnWrite | Write function pointer matching the CPLHTTPWriteFunc() semantics. May be NULL. |
pWriteArg | Argument which will pass to a write function. |
CPLHTTPResult** CPLHTTPMultiFetch | ( | const char *const * | papszURL, |
int | nURLCount, | ||
int | nMaxSimultaneous, | ||
CSLConstList | papszOptions | ||
) |
Fetch several documents at once.
papszURL | array of valid URLs recognized by underlying download library (libcurl) |
nURLCount | number of URLs of papszURL |
nMaxSimultaneous | maximum number of downloads to issue simultaneously. Any negative or zer value means unlimited. |
papszOptions | option list as a NULL-terminated array of strings. May be NULL. Refer to CPLHTTPFetch() for valid options. |
int CPLHTTPParseMultipartMime | ( | CPLHTTPResult * | psResult | ) |
Parses a MIME multipart message.
This function will iterate over each part and put it in a separate element of the pasMimePart array of the provided psResult structure.
psResult | pointer to the return value of CPLHTTPFetch() |
int CPLHTTPPopFetchCallback | ( | void | ) |
Uninstalls a callback set by CPLHTTPPushFetchCallback().
int CPLHTTPPushFetchCallback | ( | CPLHTTPFetchCallbackFunc | pFunc, |
void * | pUserData | ||
) |
Installs an alternate callback to the default implementation of CPLHTTPFetchEx().
This callback will only be used in the thread where this function has been called. It must be un-installed by CPLHTTPPopFetchCallback(), which must also be called from the same thread.
pFunc | Callback function to be called with CPLHTTPFetchEx() is called. |
pUserData | Last argument to provide to the pFunc callback. |
void CPLHTTPSetDefaultUserAgent | ( | const char * | pszUserAgent | ) |
Set the default user agent.
GDAL core will by default call this method with "GDAL/x.y.z" where x.y.z is the GDAL version number (during driver initialization). Applications may override it.
pszUserAgent | String (or nullptr to cancel the default user agent) |
void CPLHTTPSetFetchCallback | ( | CPLHTTPFetchCallbackFunc | pFunc, |
void * | pUserData | ||
) |
Installs an alternate callback to the default implementation of CPLHTTPFetchEx().
This callback will be used by all threads, unless contextual callbacks are installed with CPLHTTPPushFetchCallback().
It is the responsibility of the caller to make sure this function is not called concurrently, or during CPLHTTPFetchEx() execution.
pFunc | Callback function to be called with CPLHTTPFetchEx() is called (or NULL to restore default handler) |
pUserData | Last argument to provide to the pFunc callback. |
bool CPLIsMachineForSureGCEInstance | ( | ) |
Returns whether the current machine is surely a Google Compute Engine instance.
This does a very quick check without network access. Note: only works for Linux GCE instances.
bool CPLIsMachinePotentiallyGCEInstance | ( | ) |
Returns whether the current machine is potentially a Google Compute Engine instance.
This does a very quick check without network access. To confirm if the machine is effectively a GCE instance, metadata.google.internal must be queried.
char* GOA2GetAccessToken | ( | const char * | pszRefreshToken, |
const char * | pszScope | ||
) |
Fetch access token using refresh token.
The permanent refresh token is used to fetch a temporary (usually one hour) access token using Google OAuth2 web services.
A CPLError will be reported if the request fails for some reason. Common reasons include the refresh token having been revoked by the user or http connection problems.
pszRefreshToken | the refresh token from GOA2GetRefreshToken(). |
pszScope | the scope for which it is valid. Currently unused |
char** GOA2GetAccessTokenFromCloudEngineVM | ( | CSLConstList | papszOptions | ) |
Fetch access token using Cloud Engine internal REST API.
The default service accounts bound to the current Google Cloud Engine VM is used for OAuth2 authentication
A CPLError will be reported if the request fails for some reason. Common reasons include the refresh token having been revoked by the user or http connection problems.
papszOptions | NULL terminated list of options. None currently |
char** GOA2GetAccessTokenFromServiceAccount | ( | const char * | pszPrivateKey, |
const char * | pszClientEmail, | ||
const char * | pszScope, | ||
CSLConstList | papszAdditionalClaims, | ||
CSLConstList | papszOptions | ||
) |
Fetch access token using Service Account OAuth2.
See https://developers.google.com/identity/protocols/OAuth2ServiceAccount
A CPLError will be reported if the request fails for some reason.
pszPrivateKey | Private key as a RSA private key |
pszClientEmail | Client email |
pszScope | the service being requested |
papszAdditionalClaims | additional claims, or NULL |
papszOptions | NULL terminated list of options. None currently |
See https://developers.google.com/identity/protocols/OAuth2ServiceAccount and https://jwt.io/
char* GOA2GetAuthorizationURL | ( | const char * | pszScope | ) |
Return authorization url for a given scope.
Returns the URL that a user should visit, and use for authentication in order to get an "auth token" indicating their willingness to use a service.
Note that when the user visits this url they will be asked to login (using a google/gmail/etc) account, and to authorize use of the requested scope for the application "GDAL/OGR". Once they have done so, they will be presented with a lengthy string they should "enter into their application". This is the "auth token" to be passed to GOA2GetRefreshToken(). The "auth token" can only be used once.
This function should never fail.
pszScope | the service being requested, not yet URL encoded, such as "https://www.googleapis.com/auth/fusiontables". |
char* GOA2GetRefreshToken | ( | const char * | pszAuthToken, |
const char * | pszScope | ||
) |
Turn Auth Token into a Refresh Token.
A one time "auth token" provided by the user is turned into a reusable "refresh token" using a google oauth2 web service.
A CPLError will be reported if the translation fails for some reason. Common reasons include the auth token already having been used before, it not being appropriate for the passed scope and configured client api or http connection problems. NULL is returned on error.
pszAuthToken | the authorization token from the user. |
pszScope | the scope for which it is valid. |