cpl_http.h

Go to the documentation of this file.

/******************************************************************************
 *
 * Project:  Common Portability Library
 * Purpose:  Function wrapper for libcurl HTTP access.
 * Author:   Frank Warmerdam, warmerdam@pobox.com
 *
 ******************************************************************************
 * Copyright (c) 2006, Frank Warmerdam
 * Copyright (c) 2009, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/
 
#ifndef CPL_HTTP_H_INCLUDED
#define CPL_HTTP_H_INCLUDED
 
#include "cpl_conv.h"
#include "cpl_string.h"
#include "cpl_progress.h"
#include "cpl_vsi.h"


#ifndef CPL_HTTP_MAX_RETRY
#define CPL_HTTP_MAX_RETRY 0
#endif
 
#ifndef CPL_HTTP_RETRY_DELAY
#define CPL_HTTP_RETRY_DELAY 30.0
#endif
 
CPL_C_START

typedef struct
{ char **papszHeaders;
 GByte *pabyData; int nDataLen;
} CPLMimePart;

typedef struct
{
    int nStatus;

    char *pszContentType;

    char *pszErrBuf;

    int nDataLen;
    int nDataAlloc;

    GByte *pabyData;

    char **papszHeaders;

    int nMimePartCount;

    CPLMimePart *pasMimePart;
 
} CPLHTTPResult;

typedef size_t (*CPLHTTPFetchWriteFunc)(void *pBuffer, size_t nSize,
                                        size_t nMemb, void *pWriteArg);
 
int CPL_DLL CPLHTTPEnabled(void);
CPLHTTPResult CPL_DLL *CPLHTTPFetch(const char *pszURL,
                                    CSLConstList papszOptions);
CPLHTTPResult CPL_DLL *
CPLHTTPFetchEx(const char *pszURL, CSLConstList papszOptions,
               GDALProgressFunc pfnProgress, void *pProgressArg,
               CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg);
CPLHTTPResult CPL_DLL **CPLHTTPMultiFetch(const char *const *papszURL,
                                          int nURLCount, int nMaxSimultaneous,
                                          CSLConstList papszOptions);
 
void CPL_DLL CPLHTTPCleanup(void);
void CPL_DLL CPLHTTPDestroyResult(CPLHTTPResult *psResult);
void CPL_DLL CPLHTTPDestroyMultiResult(CPLHTTPResult **papsResults, int nCount);
int CPL_DLL CPLHTTPParseMultipartMime(CPLHTTPResult *psResult);
 
void CPL_DLL CPLHTTPSetDefaultUserAgent(const char *pszUserAgent);
 
/* -------------------------------------------------------------------- */
/* To install an alternate network layer to the default Curl one        */
/* -------------------------------------------------------------------- */
typedef CPLHTTPResult *(*CPLHTTPFetchCallbackFunc)(
    const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress,
    void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg,
    void *pUserData);
 
void CPL_DLL CPLHTTPSetFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
                                     void *pUserData);
 
int CPL_DLL CPLHTTPPushFetchCallback(CPLHTTPFetchCallbackFunc pFunc,
                                     void *pUserData);
int CPL_DLL CPLHTTPPopFetchCallback(void);
 
/* -------------------------------------------------------------------- */
/*      The following is related to OAuth2 authorization around         */
/*      google services like fusion tables, and potentially others      */
/*      in the future.  Code in cpl_google_oauth2.cpp.                  */
/*                                                                      */
/*      These services are built on CPL HTTP services.                  */
/* -------------------------------------------------------------------- */
 
char CPL_DLL *GOA2GetAuthorizationURL(const char *pszScope);
char CPL_DLL *GOA2GetRefreshToken(const char *pszAuthToken,
                                  const char *pszScope);
char CPL_DLL *GOA2GetAccessToken(const char *pszRefreshToken,
                                 const char *pszScope);
 
char CPL_DLL **GOA2GetAccessTokenFromServiceAccount(
    const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope,
    CSLConstList papszAdditionalClaims, CSLConstList papszOptions);
 
char CPL_DLL **GOA2GetAccessTokenFromCloudEngineVM(CSLConstList papszOptions);
 
CPL_C_END
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
// Not sure if this belong here, used in cpl_http.cpp, cpl_vsil_curl.cpp and
// frmts/wms/gdalhttp.cpp
void CPL_DLL *CPLHTTPSetOptions(void *pcurl, const char *pszURL,
                                const char *const *papszOptions);
char **CPLHTTPGetOptionsFromEnv(const char *pszFilename);

struct CPLHTTPRetryParameters
{
    int nMaxRetry = CPL_HTTP_MAX_RETRY;
    double dfInitialDelay = CPL_HTTP_RETRY_DELAY;
    std::string osRetryCodes{};
 
    CPLHTTPRetryParameters() = default;
    explicit CPLHTTPRetryParameters(const CPLStringList &aosHTTPOptions);
};

class CPLHTTPRetryContext
{
  public:
    explicit CPLHTTPRetryContext(const CPLHTTPRetryParameters &oParams);
 
    bool CanRetry(int response_code, const char *pszErrBuf,
                  const char *pszCurlError);
    bool CanRetry();

    double GetCurrentDelay() const;

    void ResetCounter()
    {
        m_nRetryCount = 0;
    }
 
  private:
    CPLHTTPRetryParameters m_oParameters{};
    int m_nRetryCount = 0;
    double m_dfCurDelay = 0.0;
    double m_dfNextDelay = 0.0;
};
 
void CPL_DLL *CPLHTTPIgnoreSigPipe();
void CPL_DLL CPLHTTPRestoreSigPipeHandler(void *old_handler);
bool CPLMultiPerformWait(void *hCurlMultiHandle, int &repeats);
 
bool CPL_DLL CPLIsMachinePotentiallyGCEInstance();
bool CPLIsMachineForSureGCEInstance();

class GOA2Manager
{
  public:
    GOA2Manager();

    typedef enum
    {
        NONE,
        GCE,
        ACCESS_TOKEN_FROM_REFRESH,
        SERVICE_ACCOUNT
    } AuthMethod;
 
    bool SetAuthFromGCE(CSLConstList papszOptions);
    bool SetAuthFromRefreshToken(const char *pszRefreshToken,
                                 const char *pszClientId,
                                 const char *pszClientSecret,
                                 CSLConstList papszOptions);
    bool SetAuthFromServiceAccount(const char *pszPrivateKey,
                                   const char *pszClientEmail,
                                   const char *pszScope,
                                   CSLConstList papszAdditionalClaims,
                                   CSLConstList papszOptions);

    AuthMethod GetAuthMethod() const
    {
        return m_eMethod;
    }
 
    const char *GetBearer() const;

    const CPLString &GetPrivateKey() const
    {
        return m_osPrivateKey;
    }

    const CPLString &GetClientEmail() const
    {
        return m_osClientEmail;
    }

    std::string GetKey() const
    {
        std::string osKey(std::to_string(static_cast<int>(m_eMethod))
                              .append(",client-id=")
                              .append(m_osClientId)
                              .append(",client-secret=")
                              .append(m_osClientSecret)
                              .append(",refresh-token=")
                              .append(m_osRefreshToken)
                              .append(",private-key=")
                              .append(m_osPrivateKey)
                              .append(",client-email=")
                              .append(m_osClientEmail)
                              .append(",scope=")
                              .append(m_osScope));
        osKey.append(",additional-claims=");
        for (const auto *pszOption : m_aosAdditionalClaims)
        {
            osKey.append(pszOption);
            osKey.append("+");
        }
        osKey.append(",options=");
        for (const auto *pszOption : m_aosOptions)
        {
            osKey.append(pszOption);
            osKey.append("+");
        }
        return osKey;
    }
 
  private:
    mutable CPLString m_osCurrentBearer{};
    mutable time_t m_nExpirationTime = 0;
 
    AuthMethod m_eMethod = NONE;
 
    // for ACCESS_TOKEN_FROM_REFRESH
    CPLString m_osClientId{};
    CPLString m_osClientSecret{};
    CPLString m_osRefreshToken{};
 
    // for SERVICE_ACCOUNT
    CPLString m_osPrivateKey{};
    CPLString m_osClientEmail{};
    CPLString m_osScope{};
    CPLStringList m_aosAdditionalClaims{};
 
    CPLStringList m_aosOptions{};
};
 
#endif  // __cplusplus
 
#endif /* ndef CPL_HTTP_H_INCLUDED */