465 lines
28 KiB
C
465 lines
28 KiB
C
/*
|
||
* IEC104配电自动化远程参数:Type200切区、201读区号、202读参数、203预置/固化/撤销。
|
||
* 每Slave一个可选静态实例,固定FIFO;与所属Slave在同一事件循环串行调用。
|
||
* 模块不建线程、不分配堆、不管理参数存储。Handle_Event/Process不调用应用,
|
||
* 只有Execute_Next同步调用action/lookup;应用负责点表、权限、暂存、原子发布与持久化。
|
||
* PRESET只暂存,SOLIDIFY一次性发布;CANCEL/DISCARD释放本批暂存。
|
||
* APPLIED不等于持久化完成,Send_Response接手也不等于主站收到。
|
||
* 在途任务、预置、恢复与DISCARD全部收尾前,须保持相同回调/context身份及原站存储归属。
|
||
* 主循环:分派Slave全部通知 -> Process -> Execute_Next -> Process,再按状态合并等待期限。
|
||
* 退出:停止接入 -> Cancel -> Slave_Close -> 分派通知 -> 交付DISCARD -> Destroy。
|
||
*/
|
||
#ifndef IEC104_REMOTE_PARAMETER_H
|
||
#define IEC104_REMOTE_PARAMETER_H
|
||
|
||
#include <stdbool.h>
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
#include "IEC104_Slave.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
typedef struct IEC104_RemoteParameter IEC104_RemoteParameter_t; /* 静态池句柄,不得复制对象或越过Destroy使用。 */
|
||
typedef struct IEC104_RemoteParameterFrame IEC104_RemoteParameterFrame_t; /* 仅本次lookup可写的TLV容器。 */
|
||
|
||
/* 专用类型与PI位只供本模块使用;202/203的SN不能经公共信息对象Parse解释为IOA。 */
|
||
#define IEC104_REMOTE_PARAMETER_C_SR_NA_1 200U
|
||
#define IEC104_REMOTE_PARAMETER_C_RR_NA_1 201U
|
||
#define IEC104_REMOTE_PARAMETER_C_RS_NA_1 202U
|
||
#define IEC104_REMOTE_PARAMETER_C_WS_NA_1 203U
|
||
#define IEC104_REMOTE_PARAMETER_PI_CONT 0x01U
|
||
#define IEC104_REMOTE_PARAMETER_PI_CR 0x40U
|
||
#define IEC104_REMOTE_PARAMETER_PI_SE 0x80U
|
||
#define IEC104_REMOTE_PARAMETER_MAX_VALUE_BYTES 235U
|
||
/* type映射到type_mask的低四位;宏可能重复求值,实参不得带副作用。 */
|
||
#define IEC104_REMOTE_PARAMETER_TYPE_BIT(type) ((uint8_t)( \
|
||
((type) >= 200U && (type) <= 203U) ? (1U << ((type) - 200U)) : 0U))
|
||
|
||
/* TLV的多字节值统一小端;Tag4同时用于Bytes/String,具体语义必须由地址点表区分。 */
|
||
enum {
|
||
IEC104_REMOTE_PARAMETER_TAG_BOOLEAN = 1,
|
||
IEC104_REMOTE_PARAMETER_TAG_TINY = 43,
|
||
IEC104_REMOTE_PARAMETER_TAG_UTINY = 32,
|
||
IEC104_REMOTE_PARAMETER_TAG_SHORT = 33,
|
||
IEC104_REMOTE_PARAMETER_TAG_USHORT = 45,
|
||
IEC104_REMOTE_PARAMETER_TAG_INT = 2,
|
||
IEC104_REMOTE_PARAMETER_TAG_UINT = 35,
|
||
IEC104_REMOTE_PARAMETER_TAG_LONG = 36,
|
||
IEC104_REMOTE_PARAMETER_TAG_ULONG = 37,
|
||
IEC104_REMOTE_PARAMETER_TAG_FLOAT = 38,
|
||
IEC104_REMOTE_PARAMETER_TAG_DOUBLE = 39,
|
||
IEC104_REMOTE_PARAMETER_TAG_STRING = 4
|
||
};
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_OP_SWITCH_AREA = 1,
|
||
IEC104_REMOTE_PARAMETER_OP_READ_AREA,
|
||
IEC104_REMOTE_PARAMETER_OP_READ,
|
||
IEC104_REMOTE_PARAMETER_OP_PRESET, /* 暂存整帧,不得改运行值;CONT=0才形成可固化批次。 */
|
||
IEC104_REMOTE_PARAMETER_OP_SOLIDIFY, /* 重新校验整批约束后原子发布,并释放暂存。 */
|
||
IEC104_REMOTE_PARAMETER_OP_CANCEL, /* 主站显式撤销;回调任何结果都必须清理本批暂存。 */
|
||
IEC104_REMOTE_PARAMETER_OP_DISCARD /* 模块主动终结后的清理通知,不发报文,返回值忽略。 */
|
||
} IEC104_RemoteParameterOperation_t;
|
||
|
||
/* 回调期只读借用,每次按operation完整初始化;不得保留Request指针或其元素指针。
|
||
* 原站须用identity.slave + station_id寻址;同CA删除重注册不能继承旧任务/暂存。
|
||
* DISCARD沿用首帧身份、SN、流水号与受理时刻,不携带原预置元素。
|
||
* CANCEL允许SN不匹配:按完整归属定位当前批次,不能用请求SN选择其他区的暂存。 */
|
||
typedef struct {
|
||
IEC104_SlaveEventIdentity_t identity; /* 原Slave/实例/代次,传输检查、回复及关闭始终使用此身份。 */
|
||
/* instance_id是本模块编号,不是identity.instance_id;generation镜像原TCP代次。
|
||
* receive_serial取原I帧事件流水号,不是模块自增号或线上N(S);station_id为原站注册编号。 */
|
||
uint64_t instance_id, generation, receive_serial, station_id;
|
||
uint16_t common_address; /* 原CA,仅组帧/诊断,不能据此重新选择同CA的新站。 */
|
||
uint8_t originator_address, type_id; /* 原OA/类型;OA不构成权限认证或模块会话归属键。 */
|
||
IEC104_RemoteParameterOperation_t operation;
|
||
bool test; /* TEST的201/202仍只读;200/203模拟不调用写动作,DISCARD恒为false。 */
|
||
uint16_t sn; /* 原请求SN;READ_AREA为0,DISCARD取首帧SN,CANCEL并非暂存选择器。 */
|
||
size_t count; /* PRESET元素数/READ地址数;READ为0表示读全部,其余操作均为0。 */
|
||
bool first_frame, more_follows; /* 仅PRESET有效:是否首帧/原CONT位;其余均为false。 */
|
||
uint64_t accepted_ms; /* Handle_Event保存时的Net单调毫秒;WAIT不刷新,不是墙钟时间。 */
|
||
const uint8_t *_data; /* 模块内部借用字段,只交给Get_Element;应用不得修改/保存。 */
|
||
uint16_t _length; /* 仅PRESET携带原ASDU长度,其余为0且_data为NULL。 */
|
||
} IEC104_RemoteParameterRequest_t;
|
||
|
||
typedef struct {
|
||
uint32_t ioa;
|
||
uint8_t tag, length;
|
||
const uint8_t *value; /* 指向当前PRESET原文;Get_Element不复制值,回调返回即结束借用。 */
|
||
} IEC104_RemoteParameterElement_t;
|
||
|
||
typedef struct {
|
||
uint16_t current, minimum, maximum; /* READ_AREA输出,APPLIED须满足minimum <= current <= maximum。 */
|
||
} IEC104_RemoteParameterArea_t;
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_ACTION_REJECTED = 0, /* 业务拒绝;预置/固化/正常撤销仍须完成对应清理。 */
|
||
IEC104_REMOTE_PARAMETER_ACTION_APPLIED = 1, /* 已同步完成该操作;不能先肯定再异步改变运行值。 */
|
||
IEC104_REMOTE_PARAMETER_ACTION_UNKNOWN_IOA = 2 /* 仅PRESET表示未知地址并回47;其余操作按拒绝。 */
|
||
} IEC104_RemoteParameterActionResult_t;
|
||
|
||
/* 短时同步动作;area仅READ_AREA时非NULL且进入前清零,其他操作必须忽略area。
|
||
* PRESET/SOLIDIFY失败须返回前清空本批暂存与预留,SOLIDIFY失败还须保证运行值完全不变。
|
||
* 正常CANCEL无论肯定/拒绝都须清理;需要禁止某类撤销时应在Handle_Event之前统一准入。
|
||
* 恢复态合法CANCEL由模块解除协议屏障,不再重复调用应用;DISCARD返回值始终忽略。
|
||
* 不得重入修改入口、推进Slave或改变被借用存储归属;可调用Get_Status进行只读诊断。 */
|
||
typedef IEC104_RemoteParameterActionResult_t (*IEC104_RemoteParameterAction_t)(
|
||
void *context, const IEC104_RemoteParameterRequest_t *request,
|
||
IEC104_RemoteParameterArea_t *area);
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_ADD_ERROR = -1, /* 非法借用/地址/值或重复添加,锁存本次lookup违约。 */
|
||
IEC104_REMOTE_PARAMETER_ADD_OK = 0, /* 本元素已完整复制进当前帧。 */
|
||
IEC104_REMOTE_PARAMETER_ADD_FULL = 1 /* 元素合法但本帧余量不足;已有内容保持不变。 */
|
||
} IEC104_RemoteParameterAddResult_t;
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_LOOKUP_ERROR = -1, /* 本次读取失败;模块固定否定回复,之后不再取值。 */
|
||
IEC104_REMOTE_PARAMETER_LOOKUP_END = 0, /* 只允许读全部;本次没有添加,表示点表结束。 */
|
||
IEC104_REMOTE_PARAMETER_LOOKUP_ADDED = 1, /* 本次必须恰好一次ADD_OK;指定读取还须匹配IOA。 */
|
||
IEC104_REMOTE_PARAMETER_LOOKUP_FULL = 2, /* 必须确有ADD_FULL且当前帧非空;同一下标留到下一帧。 */
|
||
IEC104_REMOTE_PARAMETER_LOOKUP_UNKNOWN = 3 /* 只允许指定读取且未添加;首帧前回47,否则负末帧。 */
|
||
} IEC104_RemoteParameterLookupResult_t;
|
||
|
||
/* 纯读取、可重复:index从0连续递增;指定读取的ioa为请求地址,读全部固定传0占位。
|
||
* 指定读取预检、正式组帧与发送WAIT重取都可能再次访问同一下标,不得消费数据或清零计数。
|
||
* 每次lookup最多加入一个元素,返回枚举必须与实际Add结果一致;frame不跨回调借用。
|
||
* 整次读全部须保持成员集合和index->IOA映射稳定,点表变化时应用返回ERROR;值允许变化。
|
||
* 模块不保存历史地址映射,不提供跨ASDU快照;index=SIZE_MAX处仅允许END,不得自增回绕。 */
|
||
typedef IEC104_RemoteParameterLookupResult_t (*IEC104_RemoteParameterLookup_t)(
|
||
void *context, const IEC104_RemoteParameterRequest_t *request,
|
||
size_t index, uint32_t ioa, IEC104_RemoteParameterFrame_t *frame);
|
||
|
||
/* 启用200/201/203须提供action,启用202须提供lookup,执行前连TEST模拟也会检查。
|
||
* 结构体本身只在调用期借用;首次执行到所有在途任务/会话/恢复/DISCARD清空期间,
|
||
* 每次Execute_Next的函数指针及context身份必须相同,指向的应用环境也须保持有效。 */
|
||
typedef struct {
|
||
IEC104_RemoteParameterAction_t action;
|
||
IEC104_RemoteParameterLookup_t lookup;
|
||
} IEC104_RemoteParameterHandlers_t;
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_CONFIRM_MIRROR = 0, /* 默认:预置肯定保留原VSQ/SN/PI/全部TLV。 */
|
||
IEC104_REMOTE_PARAMETER_CONFIRM_COMPACT_COMPAT = 1 /* 仅预置肯定裁成9字节/VSQ0,须与主站约定。 */
|
||
} IEC104_RemoteParameterPresetConfirmMode_t;
|
||
|
||
/* Create按值复制;各期限单位ms,0禁用(也禁用时钟回退判定)。
|
||
* 非零期限在now回退或elapsed >= timeout时到期,WAIT/重试不会延长期限。 */
|
||
typedef struct {
|
||
uint8_t type_mask; /* TYPE_BIT的组合,仅bit0..3有效且不能全零。 */
|
||
IEC104_RemoteParameterPresetConfirmMode_t preset_confirm_mode; /* 创建后冻结,不逐帧探测。 */
|
||
uint32_t execute_timeout_ms; /* 请求受理起算;202首个正常帧提交前仍受此限。 */
|
||
uint32_t preset_timeout_ms; /* 最近一次PRESET成功起算;终止动作结果冻结即停表。 */
|
||
uint32_t read_timeout_ms; /* 202首个正常数据帧提交OK起算,不随每帧刷新。 */
|
||
uint32_t reply_timeout_ms; /* 固定回复就绪且首次成为队首起算;到期关闭原连接。 */
|
||
} IEC104_RemoteParameterConfig_t;
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_EVENT_ERROR = -1, /* 参数/身份/重入/准备错误,不能再按未知类型回44。 */
|
||
IEC104_REMOTE_PARAMETER_EVENT_IGNORED = 0, /* 未接手:非本类型、未启用、无视图或未激活等。 */
|
||
IEC104_REMOTE_PARAMETER_EVENT_HANDLED = 1 /* 已消费,含拒绝、丢新和faulted丢弃;不等于已确认。 */
|
||
} IEC104_RemoteParameterEventResult_t;
|
||
|
||
typedef enum {
|
||
IEC104_REMOTE_PARAMETER_EXECUTE_ERROR = -1, /* 本轮任何回调/TEST模拟之前失败,可能已经故障收尾。 */
|
||
IEC104_REMOTE_PARAMETER_EXECUTE_EMPTY = 0, /* 本入口无可执行工作;队首固定回复交Process。 */
|
||
IEC104_REMOTE_PARAMETER_EXECUTE_WAIT = 1, /* 等通知/发送容量;可能已lookup,但该帧未推进游标。 */
|
||
IEC104_REMOTE_PARAMETER_EXECUTE_OK = 2 /* 已动作、模拟、清理、提交一帧或确定转态,不表示业务成功。 */
|
||
} IEC104_RemoteParameterExecuteResult_t;
|
||
|
||
/* 计数自Create累计,Cancel/启停/重连不清零;按无符号语义溢出,不充当身份编号。
|
||
* TEST参与受理/读取/发送/恢复拒绝计数,不计真实action和真实预置动作。
|
||
* 调度字段是只读快照;不能把“有任务/有会话”直接当成需要零等待。 */
|
||
typedef struct {
|
||
uint64_t generation; /* 由已分派通知建立的TCP代次,不是模块instance_id。 */
|
||
/* active只反映通知激活;events_pending须先读空;execute_pending/confirm_pending
|
||
* 表示FIFO中存在执行任务/固定回复,并不说明队首现在能推进。 */
|
||
bool active, events_pending, execute_pending, confirm_pending;
|
||
/* need_process表示可推进清理/期限/固定回复;execute_ready表示可执行队首或欠DISCARD。
|
||
* 最近发送WAIT时不忙重试;timer_active用于判定下方剩余时间是否有效。 */
|
||
bool need_process, timer_active, execute_ready;
|
||
/* preset_active包含TEST;恢复本身不启定时器;faulted粘滞到Destroy。
|
||
* DISCARD是独立清理义务,即使断线/faulted也须由Execute_Next交付。 */
|
||
bool preset_active, discard_pending, recovery_required, faulted;
|
||
uint32_t timeout_remaining_ms; /* 可处理期限的最小剩余;0为到期或无计时,须合看timer_active。 */
|
||
unsigned pending_requests; /* 占槽任务数,不包含活动会话、恢复或DISCARD独立记录。 */
|
||
unsigned long accepted, rejected, dropped_requests, timeouts; /* 合法入槽/无状态拒绝/满槽丢新/执行前到期。 */
|
||
unsigned long executed, applied, unknown_ioa; /* 真实action返回/合法APPLIED/PRESET未知地址;不含DISCARD。 */
|
||
/* 正常帧提交/正常末帧提交/已受理读取首次失败或取消/已开始读取的总期限到期。 */
|
||
unsigned long read_frames, reads_completed, reads_aborted, read_timeouts;
|
||
unsigned long presets_opened, solidified, presets_cancelled; /* 真实首帧成功/固化APPLIED/正常CANCEL结束。 */
|
||
unsigned long preset_timeouts, discards, recovery_rejected; /* 真实预置到期/DISCARD实际交付/恢复态拒绝。 */
|
||
/* Send接手/其中否定/实际Send WAIT/清除占槽任务;cancelled不按会话计数。 */
|
||
unsigned long submitted, negative_submitted, waits, cancelled;
|
||
unsigned long invalid_callbacks, reply_timeouts, send_errors, close_errors; /* 回调违约/回复超时/发送失败/关闭失败。 */
|
||
unsigned long faulted_dropped; /* 故障期间消费的本模块I帧,不计其他类型及生命周期通知。 */
|
||
} IEC104_RemoteParameterStatus_t;
|
||
|
||
/**
|
||
* 功能:填入四类型全开、MIRROR及execute/preset/read/reply=15000/60000/60000/15000ms。
|
||
* config为NULL时无操作。默认期限是工程取值,现场须与目标主站约定。
|
||
* 输入参数:config——配置。
|
||
* 输出参数:config——配置的更新结果。
|
||
* 返回值:无。
|
||
* 说明:内部调用:memset。
|
||
*/
|
||
void IEC104_RemoteParameter_Config_Default(IEC104_RemoteParameterConfig_t *config);
|
||
/**
|
||
* 功能:config非NULL且按值复制;要求COT/CA/IOA宽度2/2/3,每Slave只允许一个实例。
|
||
* 输入参数:slave——所属从站服务。
|
||
* config——配置。
|
||
* 输出参数:无。
|
||
* 返回值:按处理分支返回NULL、slot。
|
||
* 说明:允许Slave_Init前创建,但须早于首条通知消费;所属Slave寿命必须覆盖本实例。
|
||
* 非法参数、重复绑定、池满或不回绕编号耗尽返回NULL,不占槽、不保存应用回调。
|
||
* 实现编译宏IEC104_REMOTE_PARAMETER_CAPACITY默认TCP服务容量,
|
||
* IEC104_REMOTE_PARAMETER_TASK_CAPACITY默认2;两者均须大于0。
|
||
*/
|
||
IEC104_RemoteParameter_t *IEC104_RemoteParameter_Create(
|
||
IEC104_Slave_t *slave, const IEC104_RemoteParameterConfig_t *config);
|
||
/**
|
||
* 功能:不隐式取消或关闭Slave;有任务、预置、恢复、DISCARD或正在回调均返回false。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值: 回调重入、尚欠清理或故障原连接未完成关闭时返回false,实例保留。
|
||
* 说明:faulted即使队空,也须证实其原TCP已经终结;失败不归还池槽、不清应用暂存。
|
||
*/
|
||
bool IEC104_RemoteParameter_Destroy(IEC104_RemoteParameter_t *self);
|
||
/**
|
||
* 功能:取消全部占槽任务,真实预置转为待DISCARD;健康连接上保留恢复屏障。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:无。
|
||
* 说明:未执行的可识别首帧也建立恢复,防止其在途续帧被当成新批次。
|
||
* 不回滚已APPLIED动作,不撤回发送层已接手的帧;无效句柄/回调重入无操作。
|
||
*/
|
||
void IEC104_RemoteParameter_Cancel(IEC104_RemoteParameter_t *self);
|
||
/**
|
||
* 功能:按Slave FIFO交付全部通知;事件只在调用期借用,接手后复制身份和原文。
|
||
* 输入参数:self——本模块实例。
|
||
* event——事件。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:按处理分支返回IEC104_REMOTE_PARAMETER_EVENT_ERROR、IEC104_REMOTE_PARAMETER_EVENT_IGNORED、IEC104_REMOTE_PARAMETER_EVENT_HANDLED。
|
||
* 说明:生命周期仍须广播其他模块;I帧HANDLED或ERROR后不得继续未知类型兜底。
|
||
* 错误回复也入FIFO,满槽丢新;主站须逐帧获得预置肯定后再发下一帧、全部肯定后固化。
|
||
*/
|
||
IEC104_RemoteParameterEventResult_t IEC104_RemoteParameter_Handle_Event(
|
||
IEC104_RemoteParameter_t *self, const IEC104_SlaveEvent_t *event);
|
||
/**
|
||
* 功能:无应用回调,有界推进期限、原会话失效及队首固定回复;欠DISCARD时让出给Execute_Next。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:本轮协议推进及会话检查完成返回true;实例、重入、查询或内部处理失败返回false。
|
||
* 说明:true仅表示本轮正常结束,可能仍等待;false为入口/查询/发送/关闭失败或已faulted。
|
||
* 网络推进后即使need_process为false也应再调用,以重试上轮WAIT。
|
||
*/
|
||
bool IEC104_RemoteParameter_Process(IEC104_RemoteParameter_t *self);
|
||
/**
|
||
* 功能:先检查启用类型所需回调、旧预置期限,再优先交付一个DISCARD,之后才处理队首。
|
||
* 输入参数:self——本模块实例。
|
||
* handlers——回调集合。
|
||
* context——调用方上下文。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:按处理分支返回IEC104_REMOTE_PARAMETER_EXECUTE_ERROR、IEC104_REMOTE_PARAMETER_EXECUTE_OK、IEC104_REMOTE_PARAMETER_EXECUTE_EMPTY、IEC104_REMOTE_PARAMETER_EXECUTE_WAIT、Execute_Read(self, task, handlers, context)。
|
||
* 说明:每次在普通动作、DISCARD及一帧202提交中择一推进;预检与组帧可能多次lookup。
|
||
* ERROR表示本轮回调/TEST模拟前失败;动作或lookup已发生后的故障返回OK并安排收尾,
|
||
* 应用不能根据后续发送失败重做动作。WAIT可能已lookup,但未提交帧游标不推进。
|
||
* 固定回复WAIT仅重试冻结字节;202正常数据WAIT会重新lookup,不可原地忙重试。
|
||
*/
|
||
IEC104_RemoteParameterExecuteResult_t IEC104_RemoteParameter_Execute_Next(
|
||
IEC104_RemoteParameter_t *self,
|
||
const IEC104_RemoteParameterHandlers_t *handlers, void *context);
|
||
/**
|
||
* 功能:只读,可在回调内查询;失败不改输出,不隐式清理/取消或恢复faulted。
|
||
* 输入参数:self——本模块实例。
|
||
* status——状态快照。
|
||
* 输出参数:status——状态快照的更新结果。
|
||
* 返回值:!Owned(self) || status == NULL || RP_STATUS(self->slave, &transport, NULL) != IEC104_TCP_OK时返回false;其余分支返回false、true。
|
||
* 说明:零等待条件:events_pending || execute_ready || need_process;回调内抑制递归推进提示。
|
||
*/
|
||
bool IEC104_RemoteParameter_Get_Status(const IEC104_RemoteParameter_t *self,
|
||
IEC104_RemoteParameterStatus_t *status);
|
||
/**
|
||
* 功能:仅当前PRESET回调的原Request及有效下标可用;返回只读原文视图,失败不改element。
|
||
* 输入参数:request——请求。
|
||
* index——索引。
|
||
* element——IEC104_RemoteParameterElement_t *所指数据。
|
||
* 输出参数:element——IEC104_RemoteParameterElement_t *所指数据的更新结果。
|
||
* 返回值:成功解析当前预置回调中指定对象返回true;借用权限、操作、索引或原文长度非法返回false。
|
||
* 说明:Request指针、Element.value不得跨回调保存;应用暂存必须自行复制需要的值。
|
||
*/
|
||
bool IEC104_RemoteParameter_Get_Element(
|
||
const IEC104_RemoteParameterRequest_t *request, size_t index,
|
||
IEC104_RemoteParameterElement_t *element);
|
||
/**
|
||
* 功能:仅当前lookup借出的frame可用;IOA须1..0xFFFFFF,Tag/长度/Boolean/有限浮点均校验。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* tag——uint8_t值。
|
||
* value——业务值。
|
||
* length——字节长度。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:按处理分支返回Bad_Add(frame)、frame->last_add。
|
||
* 说明:value即时复制,length>0时不可NULL;length=0仅允许Tag4。失败不改变已有元素或字节。
|
||
* 每次lookup只能成功添加一个元素;非法添加/第二次添加锁存违约,后续合法调用不能掩盖。
|
||
* Tag4在此只作原始字节串处理,String语义及地址类型匹配仍由应用点表负责。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Element(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa,
|
||
uint8_t tag, const uint8_t *value, uint8_t length);
|
||
|
||
/**
|
||
* 功能:固定宽度便捷编码均汇入Add_Element,返回值与借用限制相同;整数按小端编码。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回统一添加结果。
|
||
* 说明:Float/Double还验证宿主IEEE表示后编码,拒绝NaN/Inf,接受负零和有限非规格化值。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Boolean(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, bool value);
|
||
/**
|
||
* 功能:添加Tag43有符号8位量,保留转换后的低8位线格式。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 43U, (uint64_t)value, 1U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Tiny(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, int8_t value);
|
||
/**
|
||
* 功能:添加Tag32无符号8位量,不进行比例换算。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 32U, (uint64_t)value, 1U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_UTiny(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, uint8_t value);
|
||
/**
|
||
* 功能:添加Tag33有符号16位量,以2字节小端保存低位。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 33U, (uint64_t)value, 2U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Short(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, int16_t value);
|
||
/**
|
||
* 功能:添加Tag45无符号16位量,沿用统一地址和容量检查。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 45U, (uint64_t)value, 2U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_UShort(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, uint16_t value);
|
||
/**
|
||
* 功能:添加Tag2有符号32位量,以4字节小端编码,不使用有符号右移。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 2U, (uint64_t)value, 4U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Int(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, int32_t value);
|
||
/**
|
||
* 功能:添加Tag35无符号32位量,以4字节小端编码。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 35U, (uint64_t)value, 4U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Uint(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, uint32_t value);
|
||
/**
|
||
* 功能:添加Tag36有符号64位量,转无符号后保留完整64位。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 36U, (uint64_t)value, 8U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Long(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, int64_t value);
|
||
/**
|
||
* 功能:添加Tag37无符号64位量,以8字节小端编码。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回Add_Integer(frame, ioa, 37U, (uint64_t)value, 8U)的结果。
|
||
* 说明:内部调用:Add_Integer。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Ulong(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, uint64_t value);
|
||
/**
|
||
* 功能:先核对浮点宽度/精度和1.0的实际表示,再memcpy位模式,避免别名规则与宿主格式假设。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:按处理分支返回Bad_Add(frame)、Add_Integer(frame, ioa, 38U, bits, 4U)。
|
||
* 说明:有限值检查仍统一留给Add_Element,便捷接口不能绕过原始TLV校验。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Float(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, float value);
|
||
/**
|
||
* 功能:验证本机double为binary64并编码为Tag39;有限值、借用次数及容量仍由Add_Element校验。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:按处理分支返回Bad_Add(frame)、Add_Integer(frame, ioa, 39U, bits, 8U)。
|
||
* 说明:平台表示不符时经Bad_Add锁存违约,不写入候选TLV。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Double(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa, double value);
|
||
/**
|
||
* 功能:原样编码Tag4字节串,显式长度0..235;不会追加终止符或进行ASCII语义校验。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* length——字节长度。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:返回IEC104_RemoteParameter_Add_Element(frame, ioa, 4U, value, length)的结果。
|
||
* 说明:允许零长度,沿用统一添加门禁。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_Bytes(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa,
|
||
const uint8_t *value, uint8_t length);
|
||
/**
|
||
* 功能:length是内容长度1..63,内容必须为非NUL ASCII;追加NUL使线上LENGTH为length+1。
|
||
* 输入参数:frame——报文帧。
|
||
* ioa——信息体地址。
|
||
* value——业务值。
|
||
* length——字节长度。
|
||
* 输出参数:frame——报文帧的更新结果。
|
||
* 返回值:按处理分支返回Bad_Add(frame)、IEC104_RemoteParameter_Add_Element(frame, ioa, 4U, bytes, (uint8_t)(length + 1U))。
|
||
* 说明:不使用无界strlen,不接受空字符串/中间NUL,也不能代替Bytes编码二进制数据。
|
||
*/
|
||
IEC104_RemoteParameterAddResult_t IEC104_RemoteParameter_Add_String(
|
||
IEC104_RemoteParameterFrame_t *frame, uint32_t ioa,
|
||
const char *value, size_t length);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC104_REMOTE_PARAMETER_H */
|