C SDK:读取强类型响应
本页内容
将成功响应转换成 C 结构体,并正确处理空值、数组和内存释放。
适用场景
当您需要从成功响应中读取状态、版本或金额时,可以把 JSON 解码成 C 结构体。解码是本地操作,不会再调用 API。只想保留原 JSON 的项目也可以继续使用原有响应。
先运行下方只读示例,了解如何确认签名结果;需要集成到自己的程序时,再查后面的字段和内存规则。
前提条件
- 已按 C SDK 入门下载源码包并完成一次只读调用。
- 准备自己的应用 ID 和签名任务 ID,并授予
enterprise:ReadJobs与enterprise:ReadVersions。 - 程序引入
cloudsign/openapi.h;强类型响应声明位于cloudsign/models.h。
操作步骤
- 调用 查询签名任务对应的准确产物,先确认 SDK 和 HTTP 请求成功。错误响应按错误码处理,不解码成成功结果。
- 将成功的
cloudsign_result交给cloudsign_decode_get_job_result。接收输出的指针先设为 NULL。 - 解码成功后,通过
cloudsign_response_get_job_result读取签名状态和准确产物。访问可空子对象前,先检查对应 presence 字段。 - 使用结束后调用
cloudsign_decoded_free。结构体内的字符串和子对象由解码结果统一管理,不单独释放。
运行示例
先按 C SDK 入门配置 CLOUDSIGN_BASE_URL 和同一组服务端凭据。APP_ID、JOB_ID 从自己的业务记录取得,不能用列表第一项代替原任务。
命令行示例需要哪些配置
这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。
| 变量 | 如何填写 |
|---|---|
CLOUDSIGN_BASE_URL | 网站 HTTPS 主域名 https://www.onesignios.com。 |
CLOUDSIGN_ACCESS_KEY_ID | 示例使用的长期 AccessKey ID。 |
CLOUDSIGN_ACCESS_KEY_SECRET | 同一组长期凭据的 Secret。 |
CLOUDSIGN_API_CA_FILE | 可选的 API CA 文件;默认使用系统 CA。 |
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_models_example "$APP_ID" "$JOB_ID"查看完整 models-example.c 源码
/* One authorized GET; owned typed data survives freeing the client/result. */
#include <cloudsign/openapi.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int copy_env(char *out,size_t capacity,const char *name){const char *v=getenv(name);if(!v||!*v||strlen(v)>=capacity)return 0;memcpy(out,v,strlen(v)+1);return 1;}
static const char *state_name(cloudsign_model_job_result_result_state state){
switch(state){
case CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_PENDING:return "pending";
case CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_AVAILABLE:return "available";
case CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_NOT_PRODUCED:return "not_produced";
case CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_NOT_RECORDED:return "not_recorded";
case CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_REMOVED:return "removed";
default:return NULL;
}
}
int main(int argc,char **argv){
cloudsign_credentials keys={0};cloudsign_client *client=NULL;cloudsign_result *result=NULL;cloudsign_decoded_response *decoded=NULL;
cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;
if(argc!=3){fputs("Usage: cloudsign_models_example APP_ID JOB_ID\n",stderr);goto done;}
const char *origin=getenv("CLOUDSIGN_BASE_URL");
if(!origin||!copy_env(keys.access_key_id,sizeof(keys.access_key_id),"CLOUDSIGN_ACCESS_KEY_ID")||!copy_env(keys.access_key_secret,sizeof(keys.access_key_secret),"CLOUDSIGN_ACCESS_KEY_SECRET"))goto done;
status=cloudsign_global_init();if(status!=CLOUDSIGN_OK)goto done;initialized=1;
cloudsign_options options={.origin=origin,.credentials=&keys,.ca_file=getenv("CLOUDSIGN_API_CA_FILE"),.timeout_ms=15000};status=cloudsign_client_create(&options,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
cloudsign_param path[]={{"app_id",argv[1]},{"job_id",argv[2]}};cloudsign_request request={.path=path,.path_count=2};
status=cloudsign_get_job_result(client,&request,&result);if(status!=CLOUDSIGN_OK)goto done;
status=cloudsign_decode_get_job_result(result,&decoded);if(status!=CLOUDSIGN_OK)goto done;
cloudsign_result_free(result);result=NULL;cloudsign_client_free(client);client=NULL;cloudsign_global_cleanup();initialized=0;
const cloudsign_model_job_result *data=cloudsign_response_get_job_result(decoded);const char *state=data?state_name(data->result_state):NULL;
if(!state){status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
const char *version=data->presence_signed_version==CLOUDSIGN_FIELD_VALUE&&data->signed_version?data->signed_version->id:NULL;
int available=data->result_state==CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_AVAILABLE;
if((available&&!version)||(!available&&version)){status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
printf("%s %s %s\n",cloudsign_decoded_request_id(decoded),state,version?version:"-");exit_code=available?0:2;
done:
if(exit_code==1)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(result),decoded?cloudsign_decoded_request_id(decoded):cloudsign_result_request_id(result));
cloudsign_decoded_free(decoded);cloudsign_result_free(result);cloudsign_client_free(client);cloudsign_credentials_clear(&keys);if(initialized)cloudsign_global_cleanup();return exit_code;
}
确认结果
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| 退出 0,available 且有签名包版本 ID | 该任务的准确产物可用。 | 保存返回的签名包版本 ID,再按需要申请下载。 |
| 退出 2,产物尚不可用 | 请求与解码可能成功,业务结果仍未就绪。 | 保留原签名任务 ID,按 result_state 查询或处理。 |
| 退出 1 | 配置、请求或解码失败。 | 记录安全错误码和 request_id,不使用部分结果。 |
CLI 只输出 request_id、result_state 和签名包版本 ID(没有时为“-”)。它只查询结果,不会触发签名或下载。
参数与详细规则
最先需要掌握的是字段是否存在,以及读取到的数据由谁管理。下表给出常用规则;完整边界放在展开内容中。
| 参数或对象 | 表示什么 | 使用要点 |
|---|---|---|
| presence_* | 区分未返回、明确为 null 与实际有值。 | 零、false 和空数组仍可能是有效值。 |
| decoded | 保存解码结果及其全部字段的内存对象。 | 它释放后,所有借出的字段指针一并失效。 |
| 金额与计数 | 金额保持字符串,计数使用声明中的整数类型。 | 不要把缺少的金额或统计当作零。 |
查看完整参数、内存管理与运行边界
| 类型 / 状态 | 使用规则 |
|---|---|
presence_字段名 | 每个字段都有 cloudsign_presence。CLOUDSIGN_FIELD_ABSENT 表示未返回,CLOUDSIGN_FIELD_NULL 表示明确为 null,CLOUDSIGN_FIELD_VALUE 表示有值。空串、整数 0 和布尔 false 都是有值,不能用 if(value) 判断是否返回。 |
int64_t / int / const char * | 计数 / 时间保留契约允许的精确整数(最大安全整数 9007199254740991);布尔用 int。金额始终是十进制字符串,不转为 double,不把空 / 缺失余额当作 0。 |
| 枚举 | 状态、平台等使用生成的 cloudsign_model_* 枚举。与具名常量比较;UNSET 只用于未赋值槽位,不能将 C 枚举底层数值当作 JSON 中的实际取值。整数枚举的线值也以头文件注释为准,明确区分 presence 和 JSON 中的 0。 |
| 对象与数组 | 子对象是 const 模型指针;数组是 const 包装对象,含 count 和只读 items。先确认该字段为 VALUE,再读取 items[i],且 i<count。空数组 count=0、items=NULL,不等于字段缺失。 |
| 字符串映射 | 凭证头等映射用 count / entries,每个 cloudsign_string_entry 含 key / value。这里只读取已验证数据,不自动发送 URL 或头字段;存储传输仍须使用原有严格凭证助手。 |
| 带标签的联合 | 例如身份 resources 可为 "*" 或资源数组。读取其 kind 后再使用 value.variant_1 / variant_2,不能将一种分支强转为另一种。可空单一类型使用 presence,不另造无意义的分支。 |
cloudsign_decode_result | 通用解码器从 SDK 记录的实际操作选择类型。可用 cloudsign_decoded_operation 查询操作,再选对应 getter;getUpload 和 completeUpload 即使都返回 Upload 也不能混用 getter。错误 / 缺失操作返回 COUNT 哨兵,错误 getter 返回 NULL。 |
| 已知字段与兼容 | 保留全部当前响应字段及缺失 / 可空状态。契约允许的未知扩展字段不投影到当前响应结构体;原 JSON 仍可按既有接口读取。结构布局不是稳定二进制协议,升级预览版时重新编译调用方。 |
例如签名权益 statistics=null 可能表示未获统计授权或尚无统计数据,不能当作零安装 / 零启动。读取子对象前检查 presence_statistics==CLOUDSIGN_FIELD_VALUE。同理,未返回的退款回执、重放时为空的凭证 / 凭据,与有效对象必须分别处理。
cloudsign_decoded_response *decoded = NULL;
cloudsign_status status = cloudsign_decode_get_job_result(result, &decoded);
if (status == CLOUDSIGN_OK) {
const cloudsign_model_job_result *data = cloudsign_response_get_job_result(decoded);
if (data && data->result_state == CLOUDSIGN_MODEL_JOB_RESULT_RESULT_STATE_AVAILABLE
&& data->presence_signed_version == CLOUDSIGN_FIELD_VALUE) {
const cloudsign_model_version *version = data->signed_version;
/* version->id 是此签名任务的准确签名包版本 ID;下载仍须单独申请凭证。 */
(void)version;
}
}
cloudsign_decoded_free(decoded);运行限制与错误处理
解码为纯本地操作,无需新的 global_init,不发送请求,不读取凭据提供器。只接受成功 SDK 响应;错误操作、错误 request_id、重复键、无效 UTF-8、未知枚举、不安全整数和不符合契约的数据都会拒绝,不返回部分模型。输入正文最多 2 MiB,模型缓冲最多 16 MiB,另有 JSON 树与校验期内存;超过限制返回 InvalidResponse,分配失败返回 OutOfMemory。
模型可能含短期凭据、签名 URL、设备或资金信息,仍沿用原动作 / 资源 / 账号审批。不要记录整个模型。释放会尽力清理其自有字符串及模型缓冲,不会代替调用方清理自己的副本或日志。响应类型不代表新的权限,也不自动执行付款、核销、签名或下载。
失败后如何继续
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| InvalidResponse | 响应不符合该操作的结构要求。 | 核对是否传错结果、操作或 SDK 版本,保留 request_id。 |
| OutOfMemory | 本机无法为解码结果分配内存。 | 先解决本机资源问题,不重新提交业务写入。 |
| 业务尚未成功 | failed、cancelled 或产物不可用不等于解码失败。 | 查询原任务的状态与原因,按业务规则决定下一步。 |