GDAL

- Main Page
- Related Pages
- Classes
- Files
- Download
- Issue Tracker

- File List
- File Members

Classes | Functions
cpl_http.h File Reference

Interface for downloading HTTP, FTP documents. More...

`#include "cpl_conv.h"`
`#include "cpl_string.h"`
`#include "cpl_vsi.h"`

Go to the source code of this file.

## Classes
struct | CPLMimePart
struct | CPLHTTPResult

## Functions
int | CPLHTTPEnabled (void)
| Return if CPLHTTP services can be useful. More...
CPLHTTPResult * | CPLHTTPFetch (const char *pszURL, char **papszOptions)
| Fetch a document from an url and return in a string. 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...
int | CPLHTTPParseMultipartMime (CPLHTTPResult *psResult)
| Parses a MIME multipart message. 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...

## Detailed Description

Interface for downloading HTTP, FTP documents.

## Function Documentation

void CPLHTTPDestroyResult | ( | CPLHTTPResult * | psResult | ) |

Clean the memory associated with the return value of CPLHTTPFetch()

Parameters

  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.

Returns
  TRUE if libcurl support is enabled

CPLHTTPResult* CPLHTTPFetch | ( | const char * | pszURL,
|  | char ** | papszOptions
| ) |  |

Fetch a document from an url and return in a string.

Parameters

  pszURL | valid URL recognized by underlying download library (libcurl)
  papszOptions | option list as a NULL-terminated array of strings. May be NULL. The following options are handled : CONNECTTIMEOUT=val, where val is in seconds (possibly with decimals). This is the maximum delay for the connection to be established before being aborted (GDAL >= 2.2). TIMEOUT=val, where val is in seconds. This is the maximum delay for the whole request to complete before being aborted. LOW_SPEED_TIME=val, where val is in seconds. This is the maximum time where the transfer speed should be below the LOW_SPEED_LIMIT (if not specified 1b/s), before the transfer to be considered too slow and aborted. (GDAL >= 2.1) LOW_SPEED_LIMIT=val, where val is in bytes/second. See LOW_SPEED_TIME. Has only effect if LOW_SPEED_TIME is specified too. (GDAL >= 2.1) HEADERS=val, where val is an extra header to use when getting a web page. For example "Accept: application/x-ogcwkt" HEADER_FILE=filename: filename of a text file with "key: value" headers. (GDAL >= 2.2) HTTPAUTH=[BASIC/NTLM/GSSNEGOTIATE/ANY] to specify an authentication scheme to use. USERPWD=userid:password to specify a user and password for authentication POSTFIELDS=val, where val is a nul-terminated string to be passed to the server with a POST request. PROXY=val, to make requests go through a proxy server, where val is of the form proxy.server.com:port_number PROXYUSERPWD=val, where val is of the form username:password PROXYAUTH=[BASIC/NTLM/DIGEST/ANY] to specify an proxy authentication scheme to use. NETRC=[YES/NO] to enable or disable use of $HOME/.netrc, default YES. CUSTOMREQUEST=val, where val is GET, PUT, POST, DELETE, etc.. (GDAL >= 1.9.0) COOKIE=val, where val is formatted as COOKIE1=VALUE1; COOKIE2=VALUE2; ... MAX_RETRY=val, where val is the maximum number of retry attempts if a 503 or 504 HTTP error occurs. Default is 0. (GDAL >= 2.0) RETRY_DELAY=val, where val is the number of seconds between retry attempts. Default is 30. (GDAL >= 2.0) MAX_FILE_SIZE=val, where val is a number of bytes (GDAL >= 2.2) CAINFO=/path/to/bundle.crt. This is path to Certificate Authority (CA) bundle file. By default, it will be looked in a system location. If the CAINFO options is not defined, GDAL will also look if the CURL_CA_BUNDLE environment variable is defined to use it as the CAINFO value, and as a fallback to the SSL_CERT_FILE environment variable. (GDAL >= 2.1.3)

Alternatively, if not defined in the papszOptions arguments, the CONNECTTIMEOUT, TIMEOUT, LOW_SPEED_TIME, LOW_SPEED_LIMIT, PROXY, PROXYUSERPWD, PROXYAUTH, NETRC, MAX_RETRY and RETRY_DELAY, HEADER_FILE values are searched in the configuration options named GDAL_HTTP_CONNECTTIMEOUT, GDAL_HTTP_TIMEOUT, GDAL_HTTP_LOW_SPEED_TIME, GDAL_HTTP_LOW_SPEED_LIMIT, GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD, GDAL_PROXY_AUTH, GDAL_HTTP_NETRC, GDAL_HTTP_MAX_RETRY, GDAL_HTTP_RETRY_DELAY, GDAL_HTTP_HEADER_FILE.

Returns
  a CPLHTTPResult* structure that must be freed by CPLHTTPDestroyResult(), or NULL if libcurl support is disabled

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.

Parameters

  psResult | pointer to the return value of CPLHTTPFetch()

Returns
  TRUE if the message contains MIME multipart message.

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.

Parameters

  pszRefreshToken | the refresh token from GOA2GetRefreshToken().
  pszScope | the scope for which it is valid. Currently unused

Returns
  access token, to be freed with CPLFree(), null on failure.

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.

Parameters

  pszScope | the service being requested, not yet URL encoded, such as "https://www.googleapis.com/auth/fusiontables".

Returns
  the URL to visit - should be freed with CPLFree().

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.

Parameters

  pszAuthToken | the authorization token from the user.
  pszScope | the scope for which it is valid.

Returns
  refresh token, to be freed with CPLFree(), null on failure.

Generated for GDAL by 1.8.8.