xoauth2 API 参考 - XRT 程序设计

xvalue类型

typedef struct xvalue xvalue;

xoauth2httpproc类型

传输回调：宿主提供 HTTP 能力（通用 token 交换 POST、微信 GET、JWKS/userinfo GET

extern "C" { #endif #define XOAUTH2_VERSION_MAJOR 2 #define XOAUTH2_VERSION_MINOR 0 #define XOAUTH2_VERSION_PATCH 0 enum { XOAUTH2_ERROR_ARGUMENT = 1, XOAUTH2_ERROR_STATE_MISMATCH = 2, XOAUTH2_ERROR_TOKEN_ENDPOINT = 3, XOAUTH2_ERROR_TOKEN_RESPONSE = 4, XOAUTH2_ERROR_TOKEN_DENIED = 5, XOAUTH2_ERROR_REFRESH = 6, XOAUTH2_ERROR_NETWORK = 7, XOAUTH2_ERROR_NONCE_MISMATCH = 8, }; enum { XOAUTH2_AUTH_AUTO = 0, XOAUTH2_AUTH_BODY = 1, XOAUTH2_AUTH_BASIC = 2, }; typedef bool(*xoauth2httpproc)(const char* sMethod, const char* sUrl, const char* sBody, const char* sAuthHeader, char** psResponseBody, int* piStatus, void* pContext); typedef struct xoauth2config { const char* AuthorizeUrl; const char* TokenUrl; const char* UserInfoUrl; const char* JwksUrl; const char* Issuer; const char* ClientId; const char* ClientSecret; const char* RedirectUri; const char* Scope; bool UsePkce; bool UseNonce; int AuthStyle; xoauth2httpproc Http; void* HttpContext; } xoauth2config; XRT_API void xoauth2ConfigInit(xoauth2config* pConfig); typedef struct xoauth2client { xoauth2config Config; char sState[128]; char sVerifier[128]; char sChallenge[128]; char sNonce[128]; char* pOwnedAuthUrl; char* pOwnedTokenUrl; char* pOwnedIssuerUrl; bool Wechat; } xoauth2client; XRT_API void xoauth2UseGithub(xoauth2client* pClient, const char* id, const char* secret, const char* redirect); XRT_API void xoauth2UseGoogle(xoauth2client* pClient, const char* id, const char* secret, const char* redirect); XRT_API void xoauth2UseWechat(xoauth2client* pClient, const char* appid, const char* appSecret, const char* redirect); XRT_API void xoauth2UseMicrosoft(xoauth2client* pClient, const char* id, const char* secret, const char* redirect, const char* tenant); XRT_API void xoauth2UseCustom(xoauth2client* pClient, const xoauth2config* pConfig); XRT_API void xoauth2ClientUnit(xoauth2client* pClient); XRT_API char* xoauth2BeginLogin(xoauth2client* pClient); typedef struct xoauth2token { char* AccessToken; char* RefreshToken; char* IdToken; char* OpenId; char* TokenType; int64_t ExpiresIn; char* Scope; int64_t ObtainedAt; int64_t ExpiresAt; } xoauth2token; XRT_API xoauth2token* xoauth2CompleteLogin(xoauth2client* pClient, const char* sCode, const char* sState); XRT_API void xoauth2TokenFree(xoauth2token* pToken); XRT_API xoauth2token* xoauth2Refresh(xoauth2client* pClient, const char* sRefreshToken); XRT_API bool xoauth2TokenExpiring(const xoauth2token* pToken, int leewaySeconds); XRT_API char* xoauth2HttpGet(xoauth2client* pClient, const char* sUrl, const char* sAuthHeader, int* piStatus); XRT_API bool xoauth2NonceConsume(xoauth2client* pClient, const char* sNonce); XRT_API xvalue* xoauth2GetUserInfo(xoauth2client* pClient, const char* sAccessToken); XRT_API xvalue* xoauth2GetWechatUserInfo(xoauth2client* pClient, const xoauth2token* pToken); XRT_API bool xoauth2PkceGenerate(char* sVerifier, size_t iVerifierSize, char* sChallenge, size_t iChallengeSize); XRT_API bool xoauth2StateGenerate(char* sState, size_t iStateSize); XRT_API char* xoauth2UrlEncode(const char* sText); XRT_API int xoauth2LastError(void); typedef struct xoauth2httpxrt xoauth2httpxrt; XRT_API bool xoauth2HttpXrtInit(xoauth2httpxrt* pHttp, void* pBorrowedEngine, const char* sCaPem, int64 uTimeoutMs); XRT_API void xoauth2HttpXrtUnit(xoauth2httpxrt* pHttp); XRT_API bool xoauth2HttpXrtCleanup(xoauth2httpxrt* pHttp); XRT_API xoauth2httpxrt* xoauth2HttpXrtCreate(void* pBorrowedEngine, const char* sCaPem, int64 uTimeoutMs); XRT_API void xoauth2HttpXrtDestroy(xoauth2httpxrt* pHttp); XRT_API bool xoauth2HttpXrtCleanupPending(int64 uTimeoutMs, size_t* piPending); XRT_API bool xoauth2HttpXrt(const char* sMethod, const char* sUrl, const char* sBody, const char* sAuthHeader, char** psResponseBody, int* piStatus, void* pContext)

XOAUTH2_ERROR_ARGUMENT常量

契约注释见公共头文件。

XOAUTH2_ERROR_ARGUMENT

XOAUTH2_ERROR_STATE_MISMATCH常量

契约注释见公共头文件。

XOAUTH2_ERROR_STATE_MISMATCH

XOAUTH2_ERROR_TOKEN_ENDPOINT常量

契约注释见公共头文件。

XOAUTH2_ERROR_TOKEN_ENDPOINT

XOAUTH2_ERROR_TOKEN_RESPONSE常量

契约注释见公共头文件。

XOAUTH2_ERROR_TOKEN_RESPONSE

XOAUTH2_ERROR_TOKEN_DENIED常量

契约注释见公共头文件。

XOAUTH2_ERROR_TOKEN_DENIED

XOAUTH2_ERROR_REFRESH常量

契约注释见公共头文件。

XOAUTH2_ERROR_REFRESH

XOAUTH2_ERROR_NETWORK常量

契约注释见公共头文件。

XOAUTH2_ERROR_NETWORK

XOAUTH2_ERROR_NONCE_MISMATCH常量

契约注释见公共头文件。

XOAUTH2_ERROR_NONCE_MISMATCH

XOAUTH2_AUTH_AUTO常量

契约注释见公共头文件。

XOAUTH2_AUTH_AUTO

XOAUTH2_AUTH_BODY常量

契约注释见公共头文件。

XOAUTH2_AUTH_BODY

XOAUTH2_AUTH_BASIC常量

契约注释见公共头文件。

XOAUTH2_AUTH_BASIC

xoauth2config类型

自定义端点配置（授权/token/userinfo/JWKS URL 与 scope）。

typedef struct xoauth2config { ... } xoauth2config;

xoauth2client类型

客户端（含运行时会话状态：state + PKCE verifier + nonce）

typedef struct xoauth2client { ... } xoauth2client;

xoauth2token类型

回调处理：用授权码换 token。

typedef struct xoauth2token { ... } xoauth2token;

xoauth2ConfigInit函数

自定义端点配置零值。

XRT_API void xoauth2ConfigInit(xoauth2config* pConfig)

xoauth2UseGithub函数

Provider 预设（一行初始化）。tenant 超 256 字符时 Microsoft 预设

XRT_API void xoauth2UseGithub(xoauth2client* pClient, const char* id, const char* secret, const char* redirect)

xoauth2UseGoogle函数

一键套用 Google 端点（授权码流程）。

XRT_API void xoauth2UseGoogle(xoauth2client* pClient, const char* id, const char* secret, const char* redirect)

xoauth2UseWechat函数

一键套用微信开放平台端点。

XRT_API void xoauth2UseWechat(xoauth2client* pClient, const char* appid, const char* appSecret, const char* redirect)

xoauth2UseMicrosoft函数

一键套用 Microsoft/Azure AD 端点（含 tenant）。

XRT_API void xoauth2UseMicrosoft(xoauth2client* pClient, const char* id, const char* secret, const char* redirect, const char* tenant)

xoauth2UseCustom函数

套用自定义端点配置。

XRT_API void xoauth2UseCustom(xoauth2client* pClient, const xoauth2config* pConfig)

xoauth2ClientUnit函数

会话终止/客户端重置：清零 state/verifier（敏感）并释放预设持有的

XRT_API void xoauth2ClientUnit(xoauth2client* pClient)

xoauth2BeginLogin函数

生成授权 URL（含 state + PKCE）。

XRT_API char* xoauth2BeginLogin(xoauth2client* pClient)

xoauth2CompleteLogin函数

用回调 code 换取令牌（含 state 校验与 PKCE）。

XRT_API xoauth2token* xoauth2CompleteLogin(xoauth2client* pClient, const char* sCode, const char* sState)

xoauth2TokenFree函数

释放令牌对象。

XRT_API void xoauth2TokenFree(xoauth2token* pToken)

xoauth2Refresh函数

刷新 token；成功返回新 token，失败 NULL。旧 token 由调用方释放。

XRT_API xoauth2token* xoauth2Refresh(xoauth2client* pClient, const char* sRefreshToken)

xoauth2TokenExpiring函数

判断 token 是否将在 leewaySeconds 秒内过期（按 ExpiresAt 与当前时钟）。

XRT_API bool xoauth2TokenExpiring(const xoauth2token* pToken, int leewaySeconds)

xoauth2HttpGet函数

经客户端配置的传输回调执行 GET，返回响应体文本（xrtFree），

XRT_API char* xoauth2HttpGet(xoauth2client* pClient, const char* sUrl, const char* sAuthHeader, int* piStatus)

xoauth2NonceConsume函数

OIDC nonce 消费：与 BeginLogin 生成的 nonce 常时比对，

XRT_API bool xoauth2NonceConsume(xoauth2client* pClient, const char* sNonce)

xoauth2GetUserInfo函数

GET UserInfoUrl + Authorization: Bearer <accessToken>，

XRT_API xvalue* xoauth2GetUserInfo(xoauth2client* pClient, const char* sAccessToken)

xoauth2GetWechatUserInfo函数

微信专用 userinfo；pToken 必须来自微信授权或刷新响应且含 OpenId。

XRT_API xvalue* xoauth2GetWechatUserInfo(xoauth2client* pClient, const xoauth2token* pToken)

xoauth2PkceGenerate函数

生成 PKCE code_verifier（随机 43 字符）+ challenge (S256 Base64URL)

XRT_API bool xoauth2PkceGenerate(char* sVerifier, size_t iVerifierSize, char* sChallenge, size_t iChallengeSize)

xoauth2StateGenerate函数

生成随机 state（URL-safe 字符串）

XRT_API bool xoauth2StateGenerate(char* sState, size_t iStateSize)

xoauth2UrlEncode函数

URL 百分号编码

XRT_API char* xoauth2UrlEncode(const char* sText)

xoauth2LastError函数

错误便捷读取：返回当前执行上下文中 xoauth2 域错误码

XRT_API int xoauth2LastError()

xoauth2HttpXrtInit函数

零值可用；pBorrowedEngine 借用宿主 net engine（NULL 则自建），

XRT_API bool xoauth2HttpXrtInit(xoauth2httpxrt* pHttp, void* pBorrowedEngine, const char* sCaPem, int64 uTimeoutMs)

xoauth2HttpXrtUnit函数

同步清理直连传输（语义见上方 Cleanup 注释）。

XRT_API void xoauth2HttpXrtUnit(xoauth2httpxrt* pHttp)

xoauth2HttpXrtCleanup函数

与请求串行调用；等待自建 engine 的异步 Close/Abort，最多 uTimeoutMs。

XRT_API bool xoauth2HttpXrtCleanup(xoauth2httpxrt* pHttp)

xoauth2HttpXrtCreate函数

堆版本（opaque 结构无法栈上声明时用——脚本层/绑定层的正路；

XRT_API xoauth2httpxrt* xoauth2HttpXrtCreate(void* pBorrowedEngine, const char* sCaPem, int64 uTimeoutMs)

xoauth2HttpXrtDestroy函数

堆句柄销毁（先 Cleanup 成功再释放）。

XRT_API void xoauth2HttpXrtDestroy(xoauth2httpxrt* pHttp)

xoauth2HttpXrtCleanupPending函数

重试未交付失败堆构造的引擎退休；并发可用，入列不分配且不启动后台线程。

XRT_API bool xoauth2HttpXrtCleanupPending(int64 uTimeoutMs, size_t* piPending)

xoauth2HttpXrt函数

交付最多 1 MiB 的 C 字符串正文（拒绝原始 NUL），调用方用 xrtFree 释放。

XRT_API bool xoauth2HttpXrt(const char* sMethod, const char* sUrl, const char* sBody, const char* sAuthHeader, char** psResponseBody, int* piStatus, void* pContext)