Files
STM32F4-Base/IEC60870-Slave/104/IEC104_Slave.c
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

1670 lines
85 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 104子站业务入口:拥有一个TcpServer,并把底层I帧通知转换为ASDU视图和应答接口。
* 职责分工:Slave管理业务入口和事件绑定;TcpServer管理socket、调度、队列及协议会话。
* 本层只保存不透明的TcpServer指针,通过公开函数操作它,不访问其成员或复制底层对象。
*
* 生命周期:Create -> 统一启动配置/Init -> Poll或Prepare/Process -> Close -> 读空事件 -> Destroy。
* 接收路径:TcpServer_NextEvent -> 复制原文及来源身份 -> Bind_Event -> 应用处理。
* 应答路径:IEC60870_MasterConnection_Send_* -> 本文件的发送适配 -> TcpServer_Send_Response。
* 主动上报:Slave_Enqueue_Event -> 服务级NORMAL队列,不借用某个请求的连接身份。
* 本层不自动执行业务命令或发送确认;ASDU检查及业务许可仍由应用负责。
*
* 两种身份分别解决不同的复用问题:serial标识本次Slave_Create,generation标识原TCP会话。
* 事件保存两者,防止延迟应答误发给重连的主站或静态槽复用后的另一服务。
* 共用站点表只管理CA路由和节点寿命;总召等业务按注册编号保留原站,点表仍由应用管理。
* 节点的引用寿命与TCP会话寿命分开,持有节点并不表示原连接仍可应答。
* 所有调用在所属事件循环线程串行执行;静态池没有锁,Create/Destroy也须跨服务串行。
*/
#include "IEC104_Slave.h"
#include "IEC104_TcpServer.h"
#include "IEC104_TcpServer_Config.h"
#include <string.h>
/* 104专用默认布局来自IEC104_Types.h;共用ASDU模块通过参数工作,不硬编码104布局。
* 静态只读存储供接收视图和主动上报共用,返回的参数指针不依赖某个服务或事件的寿命。 */
static const IEC60870_AppLayerParameters_t parameters104 = IEC104_APP_LAYER_PARAMETERS_DEFAULT;
/* 完整类型仅在本文件可见;业务只保存Create返回的指针。 */
struct IEC104_Slave {
IEC104_TcpServer_t *server; /* 私有TCP服务;NULL表示该Slave槽空闲,Close不会清除此成员。 */
uint64_t serial; /* 每次成功Create递增,Destroy保留;到UINT64_MAX后不再复用该槽。 */
IEC104_Station_t *stations; /* 调用方节点按注册顺序排列,含待回收的退役节点;不另分配站点池。 */
uint32_t station_locks; /* 固定站点集合的嵌套借用计数,不是线程锁。 */
uint32_t station_snapshots; /* 活动遍历期间不回收退役节点,保护所有游标。 */
uint64_t station_serial; /* 注册编号不随Destroy清零,避免同CA替换/服务槽复用混淆。 */
};
_Static_assert(IEC104_TCP_SERVER_CAPACITY > 0U, "Slave needs at least one service slot");
/* Slave和TcpServer各有对象池;每个Slave占用一个底层名额,直接创建TCP服务也占该名额。 */
static IEC104_Slave_t slave_pool[IEC104_TCP_SERVER_CAPACITY];
/**
* 功能:将共用主站连接接口的布尔发送调用转换为从站应答提交。
* 输入参数:connection——绑定从站事件的共用连接接口;asdu——待提交ASDU。
* 输出参数:无。
* 返回值:底层返回SUBMIT_OK时为true,等待或任何错误均为false。
* 说明:复用Submit_ASDU完成事件身份检查和结果记录;true仅表示已接手。
*/
static bool Send_ASDU(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu);
/**
* 功能:判断句柄是否指向当前占用的Slave静态槽,NULL和池外地址返回false。
* 输入参数:self——本模块实例。
* 输出参数:无。
* 返回值:true表示句柄属于当前占用的Slave槽且仍持有底层服务,否则false。
* 说明:先按地址查池再解引用;server非空只表示拥有底层对象,不代表已Init或已连接。
* 槽复用后,单独的旧句柄副本无法与新句柄区分;Destroy成功后业务必须停止使用旧句柄。
*/
static bool Slave_Owned(const IEC104_Slave_t *self)
{
size_t index;
for (index = 0U; index < IEC104_TCP_SERVER_CAPACITY; ++index) {
if (self == &slave_pool[index]) { return self->server != NULL; }
}
return false;
}
/**
* 功能:先在本服务的链表中按地址查找,再读取目标节点;外来节点不借用其_owner字段找服务。
* 输入参数:self——本模块实例。
* station——逻辑站点。
* 输出参数:无。
* 返回值:按处理分支返回NULL、current。
* 说明:同时接受尚未回收的退役节点,以便原业务继续Acquire/Release;这里不判断CA路由资格。
*/
static IEC104_Station_t *find_owned_station(const IEC104_Slave_t *self,
const IEC104_Station_t *station)
{
IEC104_Station_t *current;
if (!Slave_Owned(self) || station == NULL) { return NULL; }
for (current = self->stations; current != NULL; current = current->_next) {
if (current == station) { return current; }
}
return NULL;
}
/**
* 功能:活动快照可能停在任意节点,因此全部快照End前都不摘除退役节点。
* 输入参数:self——本模块实例。
* 输出参数:无。
* 返回值:无。
* 说明:无快照且已删除、引用归零时才摘链并清零;不释放调用方的节点或context存储。
* Remove/Release/快照End均尝试回收,调用方据Is_Reusable决定何时释放自己的存储。
*/
static void collect_retired_stations(IEC104_Slave_t *self)
{
IEC104_Station_t **entry = &self->stations;
if (self->station_snapshots != 0U) { return; }
while (*entry != NULL) {
IEC104_Station_t *station = *entry;
if (!station->_registered && station->_users == 0U) {
*entry = station->_next;
memset(station, 0, sizeof(*station));
} else { entry = &station->_next; }
}
}
/**
* 功能:借用调用方节点,成功前不改链表或节点;
* 输入参数:self——本模块实例。
* station——逻辑站点。
* common_address——ASDU公共地址。
* context——调用方上下文。
* 输出参数:station——逻辑站点的更新结果。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_ALREADY_REGISTERED、IEC104_STATION_BUSY、IEC104_STATION_LIMIT、IEC104_STATION_DUPLICATE_CA、IEC104_STATION_OK。
* 说明:不创建通信资源,不分配点表。
*/
IEC104_StationResult_t IEC104_Slave_Add_Station(IEC104_Slave_t *self,
IEC104_Station_t *station, uint16_t common_address, void *context)
{
IEC104_Station_t **tail;
if (!Slave_Owned(self) || station == NULL || common_address == 0U ||
common_address == IEC104_CA_BROADCAST) { return IEC104_STATION_INVALID_ARGUMENT; }
if (station->_owner != NULL) { return IEC104_STATION_ALREADY_REGISTERED; }
if (self->station_locks != 0U) { return IEC104_STATION_BUSY; }
if (self->station_serial == UINT64_MAX) { return IEC104_STATION_LIMIT; }
for (tail = &self->stations; *tail != NULL; tail = &(*tail)->_next) {
if ((*tail)->_registered && (*tail)->_common_address == common_address) {
return IEC104_STATION_DUPLICATE_CA;
}
}
station->_next = NULL;
station->_owner = self;
station->_context = context;
station->_users = 0U;
station->_common_address = common_address;
station->_id = ++self->station_serial;
station->_registered = true;
station->_startup_activation = station->_startup_owner = station->_startup_request = 0U;
station->_startup_ticket = 0U;
station->_startup_completed = false;
*tail = station;
return IEC104_STATION_OK;
}
/**
* 功能:删除先退出路由,引用和快照决定实际回收时机;OK不代表节点已可释放。
* 输入参数:self——本模块实例。
* station——逻辑站点。
* 输出参数:station——逻辑站点的更新结果。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_BUSY、IEC104_STATION_OK。
* 说明:保留中的旧节点不会挡住相同CA的新注册,原业务仍通过注册编号找到旧节点。
*/
IEC104_StationResult_t IEC104_Slave_Remove_Station(IEC104_Slave_t *self, IEC104_Station_t *station)
{
if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; }
if (find_owned_station(self, station) == NULL || !station->_registered) { return IEC104_STATION_NOT_FOUND; }
if (self->station_locks != 0U) { return IEC104_STATION_BUSY; }
station->_registered = false;
collect_retired_stations(self);
return IEC104_STATION_OK;
}
/**
* 功能:新请求只匹配仍注册的节点;
* 输入参数:self——本模块实例。
* common_address——ASDU公共地址。
* 输出参数:无。
* 返回值:返回借用指针,不自动增加引用或决定广播范围。
* 说明:返回借用指针,不自动增加引用或决定广播范围。
*/
IEC104_Station_t *IEC104_Slave_Get_Station(const IEC104_Slave_t *self, uint16_t common_address)
{
IEC104_Station_t *station;
if (!Slave_Owned(self) || common_address == 0U || common_address == IEC104_CA_BROADCAST) { return NULL; }
for (station = self->stations; station != NULL; station = station->_next) {
if (station->_registered && station->_common_address == common_address) { return station; }
}
return NULL;
}
/**
* 功能:不另存可失配的数量;
* 输入参数:self——本模块实例。
* 输出参数:无。
* 返回值:按处理分支返回0U、count。
* 说明:上限仅由可注册CA和调用方存储决定。
*/
size_t IEC104_Slave_Get_Station_Count(const IEC104_Slave_t *self)
{
const IEC104_Station_t *station;
size_t count = 0U;
if (!Slave_Owned(self)) { return 0U; }
for (station = self->stations; station != NULL; station = station->_next) {
if (station->_registered) { ++count; }
}
return count;
}
/**
* 功能:普通遍历读取当前注册集合;
* 输入参数:self——本模块实例。
* current——当前节点。
* 输出参数:无。
* 返回值:按处理分支返回NULL、station。
* 说明:跨循环固定集合须Lock,允许增删的遍历须用Snapshot。
*/
IEC104_Station_t *IEC104_Slave_Next_Station(const IEC104_Slave_t *self, const IEC104_Station_t *current)
{
IEC104_Station_t *station;
if (!Slave_Owned(self)) { return NULL; }
station = current == NULL ? self->stations : find_owned_station(self, current);
if (current != NULL && station != NULL) { station = station->_next; }
while (station != NULL && !station->_registered) { station = station->_next; }
return station;
}
/**
* 功能:固定遍历集合,不锁点值;
* 输入参数:self——本模块实例。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。
* 说明:串行事件循环中的嵌套借用必须显式配对。
*/
IEC104_StationResult_t IEC104_Slave_Lock_Stations(IEC104_Slave_t *self)
{
if (!Slave_Owned(self)) { return IEC104_STATION_INVALID_ARGUMENT; }
if (self->station_locks == UINT32_MAX) { return IEC104_STATION_LIMIT; }
++self->station_locks;
return IEC104_STATION_OK;
}
/**
* 功能:归还一次站点集合借用,减少站点注册变更的保护计数。
* 输入参数:self——持有借用锁的从站服务。
* 输出参数:无。
* 返回值:OK已归还;INVALID_ARGUMENT为实例无效或没有可归还的锁。
* 说明:须与Lock_Stations配对;这是集合借用计数,不是线程互斥锁,也不锁定站点业务数据。
*/
IEC104_StationResult_t IEC104_Slave_Unlock_Stations(IEC104_Slave_t *self)
{
if (!Slave_Owned(self) || self->station_locks == 0U) { return IEC104_STATION_INVALID_ARGUMENT; }
--self->station_locks;
return IEC104_STATION_OK;
}
/**
* 功能:持有具体节点,不重新按CA路由;
* 输入参数:self——本模块实例。
* station——逻辑站点。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_LIMIT、IEC104_STATION_OK。
* 说明:尚被保留的退役节点也能取得引用,供原业务继续处理。
*/
IEC104_StationResult_t IEC104_Slave_Acquire_Station(IEC104_Slave_t *self, IEC104_Station_t *station)
{
if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; }
if (find_owned_station(self, station) == NULL) { return IEC104_STATION_NOT_FOUND; }
if (station->_users == UINT32_MAX) { return IEC104_STATION_LIMIT; }
++station->_users;
return IEC104_STATION_OK;
}
/**
* 功能:归还自己的引用后可能立即摘链清零;
* 输入参数:self——本模块实例。
* station——逻辑站点。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_OK。
* 说明:没有其他寿命保护时,不再使用该节点或context。
*/
IEC104_StationResult_t IEC104_Slave_Release_Station(IEC104_Slave_t *self, IEC104_Station_t *station)
{
if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; }
if (find_owned_station(self, station) == NULL) { return IEC104_STATION_NOT_FOUND; }
if (station->_users == 0U) { return IEC104_STATION_INVALID_ARGUMENT; }
--station->_users;
collect_retired_stations(self);
return IEC104_STATION_OK;
}
/**
* 功能:延迟事件按原注册编号找回节点,包括被引用/快照保留的退役节点,避免同CA替换串站。
* 输入参数:self——本模块实例。
* station_id——站点编号。
* 输出参数:无。
* 返回值: 与按CA查找一样只返回借用指针;
* 说明:与按CA查找一样只返回借用指针;需要独立持有时仍须Acquire。
*/
IEC104_Station_t *IEC104_Slave_Get_Station_By_Id(const IEC104_Slave_t *self, uint64_t station_id)
{
IEC104_Station_t *station;
if (!Slave_Owned(self) || station_id == 0U) { return NULL; }
for (station = self->stations; station != NULL; station = station->_next) {
if (station->_id == station_id) { return station; }
}
return NULL;
}
/**
* 功能:取得站点在所属服务中的身份编号。
* 输入参数:station——仍由服务持有的站点对象。
* 输出参数:无。
* 返回值:站点编号;空指针或已解除服务归属时返回0。
* 说明:有归属不等于仍在注册表中,是否注册须另查Is_Registered。
*/
uint64_t IEC104_Station_Get_Id(const IEC104_Station_t *station)
{
return station != NULL && station->_owner != NULL ? station->_id : 0U;
}
/**
* 功能:查询站点是否仍归属于服务且处于已注册状态。
* 输入参数:station——待查询的站点对象。
* 输出参数:无。
* 返回值:有服务归属且注册标志有效时为true,空指针或其他状态为false。
* 说明:只读取状态,不借用对象或延长其存储寿命。
*/
bool IEC104_Station_Is_Registered(const IEC104_Station_t *station)
{
return station != NULL && station->_owner != NULL && station->_registered;
}
/**
* 功能:判断站点存储是否已完全解除服务归属,可用于后续注册。
* 输入参数:station——待复用的站点对象。
* 输出参数:无。
* 返回值:对象非空且无所属服务时为true,否则为false。
* 说明:注销后若仍有借用,服务归属尚未释放,不能仅凭未注册状态复用该存储。
*/
bool IEC104_Station_Is_Reusable(const IEC104_Station_t *station)
{
return station != NULL && station->_owner == NULL;
}
/**
* 功能:只保存注册编号上界和遍历位置,不冻结IOA或点值,也不阻止站点增删。
* 输入参数:self——本模块实例。
* snapshot——快照。
* 输出参数:snapshot——快照的更新结果。
* 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。
* 说明:注册编号单调递增,后来加入的同CA替代节点也会落在本次上界之外。
*/
IEC104_StationResult_t IEC104_Slave_StationSnapshot_Begin(IEC104_Slave_t *self,
IEC104_StationSnapshot_t *snapshot)
{
if (!Slave_Owned(self) || snapshot == NULL || snapshot->_owner != NULL) {
return IEC104_STATION_INVALID_ARGUMENT;
}
if (self->station_snapshots == UINT32_MAX) { return IEC104_STATION_LIMIT; }
snapshot->_owner = self;
snapshot->_next = self->stations;
snapshot->_last_id = self->station_serial;
snapshot->_self = snapshot;
++self->station_snapshots;
return IEC104_STATION_OK;
}
/**
* 功能:先推进游标再返回当前仍注册的节点;删除的未来节点跳过,新增节点不纳入。
* 输入参数:snapshot——快照。
* 输出参数:snapshot——快照的更新结果。
* 返回值:先推进游标再返回当前仍注册的节点;
* 返回NULL只表示遍历完毕,仍须End归还保护。
* 说明:快照保护节点存储但不自动Acquire;返回NULL只表示遍历完毕,仍须End归还保护。
*/
IEC104_Station_t *IEC104_Slave_StationSnapshot_Next(IEC104_StationSnapshot_t *snapshot)
{
if (snapshot == NULL || snapshot->_self != snapshot || !Slave_Owned(snapshot->_owner)) { return NULL; }
while (snapshot->_next != NULL) {
IEC104_Station_t *station = snapshot->_next;
snapshot->_next = station->_next;
if (station->_id > snapshot->_last_id) { snapshot->_next = NULL; return NULL; }
if (station->_registered) { return station; }
}
return NULL;
}
/**
* 功能:与Begin配对一次;最后一个快照结束会尝试回收所有无引用的退役节点。
* 输入参数:snapshot——快照。
* 输出参数:snapshot——快照的更新结果。
* 返回值: 业务若要跨End继续使用Next返回的节点,必须提前Acquire。
* 说明:业务若要跨End继续使用Next返回的节点,必须提前Acquire。
*/
IEC104_StationResult_t IEC104_Slave_StationSnapshot_End(IEC104_StationSnapshot_t *snapshot)
{
IEC104_Slave_t *self;
if (snapshot == NULL || snapshot->_self != snapshot || !Slave_Owned(snapshot->_owner)) {
return IEC104_STATION_INVALID_ARGUMENT;
}
self = snapshot->_owner;
--self->station_snapshots;
memset(snapshot, 0, sizeof(*snapshot));
collect_retired_stations(self);
return IEC104_STATION_OK;
}
/**
* 功能:读取站点所属服务保存的ASDU公共地址。
* 输入参数:station——站点对象。
* 输出参数:无。
* 返回值:仍有服务归属时返回公共地址;空指针或无归属时返回0。
* 说明:本函数不检查站点是否仍在注册表内。
*/
uint16_t IEC104_Station_Get_Common_Address(const IEC104_Station_t *station)
{
return station != NULL && station->_owner != NULL ? station->_common_address : 0U;
}
/**
* 功能:取得站点注册时绑定的业务上下文。
* 输入参数:station——站点对象。
* 输出参数:无。
* 返回值:仍有服务归属时返回上下文指针;空指针或无归属时返回NULL。
* 说明:上下文可以本来就是NULL;返回指针不转移所有权,也不延长业务存储寿命。
*/
void *IEC104_Station_Get_Context(const IEC104_Station_t *station)
{
return station != NULL && station->_owner != NULL ? station->_context : NULL;
}
/**
* 功能:返回本层校验失败的结果,同时完整填写可选的error。
* 输入参数:result——本层检测出的错误;error——调用方诊断存储,允许NULL。
* 输出参数:error——错误诊断的更新结果。
* 返回值:功能:返回本层校验失败的结果,同时完整填写可选的error。
* 说明:阶段统一为VALIDATE,socket_error为0;底层操作的诊断直接透传,不在这里改写。
*/
static IEC104_TcpResult_t Slave_Error(IEC104_TcpResult_t result, IEC104_TcpError_t *error)
{
if (error != NULL) {
error->result = result;
error->stage = IEC104_TCP_STAGE_VALIDATE;
error->socket_error = 0;
}
return result;
}
/**
* 功能:从共用连接接口取回它所属的Slave事件;接口不匹配时返回NULL。
* 输入参数:connection——连接对象。
* 输出参数:无。
* 返回值:接口不匹配时返回NULL。
* 说明:同时核对发送函数和事件内接口的地址,拒绝赋值/memcpy产生的未修复副本。
* 此处只检查接口绑定,服务所有权、serial和连接代次由发送路径继续检查。
* connection及其object必须仍指向有效存储,不能用此检查代替业务的对象寿命管理。
*/
static IEC104_SlaveEvent_t *Get_Context(const IEC60870_MasterConnection_t *connection)
{
IEC104_SlaveEvent_t *event;
if (connection == NULL || connection->send_asdu != Send_ASDU || connection->object == NULL) {
return NULL;
}
event = (IEC104_SlaveEvent_t *)connection->object;
return &event->connection == connection ? event : NULL;
}
/**
* 功能:确认待发送ASDU使用可由本接入层处理的104应用层布局。
* 输入参数:parameters——应用层参数。
* 输出参数:无。
* 返回值:基础参数合法、COT/CA/IOA为2/2/3字节且ASDU上限不超过249时为true。
* 说明:允许业务采用更小的最大长度或不同默认OA;这里不检查具体信息对象和业务权限。
*/
static bool Parameters_Compatible(const IEC60870_AppLayerParameters_t *parameters)
{
return IEC60870_AppLayerParameters_Valid(parameters) &&
parameters->sizeOfCOT == 2 && parameters->sizeOfCA == 2 && parameters->sizeOfIOA == 3 &&
parameters->maxSizeOfASDU <= IEC104_MAX_ASDU_LEN;
}
/**
* 功能:完整事件和紧凑身份共用发送校验,不把旧身份替换成当前连接。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* asdu——ASDU报文。
* ticket——应答交接票据。
* priority——优先级。
* 输出参数:self——本模块实例的更新结果。
* ticket——应答交接票据的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TcpServer_Send_Response_Tracked_Priority(self->server, identity->generation, data, length, ticket, priority)。
* 说明:self只在确认仍被静态池占用后解引用;队列策略、发送期限和FATAL语义保持由TcpServer处理。
*/
static IEC104_TcpSubmitResult_t Submit_Response_Priority(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket,
IEC104_BusinessPriority_t priority)
{
const uint8_t *data;
uint16_t length;
if (!Slave_Owned(self) || identity == NULL || identity->slave != self ||
identity->instance_id != self->serial || identity->generation == 0U ||
asdu == NULL || !Parameters_Compatible(asdu->parameters) ||
IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
return IEC104_TcpServer_Send_Response_Tracked_Priority(self->server, identity->generation, data, length, ticket, priority);
}
/**
* 功能:使用默认业务等级提交应答,复用实例、事件身份和ASDU格式校验。
* 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。
* 输出参数:ticket——可选交接票据,仅最终提交成功时发布。
* 返回值:OK已接手;WAIT未接手;ERROR为身份或输入非法;FATAL为连接故障。
* 说明:不修改输入ASDU;默认等级由底层带等级入口解释。
*/
static IEC104_TcpSubmitResult_t Submit_Response(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket)
{
return Submit_Response_Priority(self, identity, asdu, ticket, (IEC104_BusinessPriority_t)0);
}
/**
* 功能:与普通请求应答不同,空闲快照每次都必须让出尚未分派的通知。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK、IEC104_TCP_SUBMIT_WAIT。
* 说明:Query和Send共用此检查:包括I_FRAME、RECORD,以及上一帧发送尾部刚交付的通知。
* 先核对实例归属,再查代次和FIFO;外来身份不能因本实例恰有通知而被误报为可重试的WAIT。
*/
static IEC104_TcpSubmitResult_t Idle_Session_Ready(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity)
{
if (!Slave_Owned(self) || identity == NULL || identity->slave != self ||
identity->instance_id != self->serial) { return IEC104_TCP_SUBMIT_ERROR; }
switch (IEC104_Slave_Check_Request(self, identity)) {
case IEC104_SLAVE_REQUEST_READY: return IEC104_TCP_SUBMIT_OK;
case IEC104_SLAVE_REQUEST_WAIT_EVENTS: return IEC104_TCP_SUBMIT_WAIT;
default: return IEC104_TCP_SUBMIT_ERROR;
}
}
/**
* 功能:按原活动轮次放行NORMAL/IDLE;本入口只执行身份/发送门禁校验,不代替业务完成判定。
* identity保存Slave实例及TCP代次,activation_id还区分同一TCP内的不同START轮次。
* 先让出完整通知FIFO,避免旧总召完成跨过尚未分派的STOP/START释放新一轮门禁。
* WAIT不改身份或消费通知;调用方先分派通知再重试,不能用当前轮次替换旧任务的轮次。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* activation_id——START活动轮次编号。
* 输出参数:self——本模块实例的更新结果。
* 返回值:按处理分支返回ready、IEC104_TcpServer_Release_Startup(self->server, identity->generation, activation_id)。
* 说明:内部调用:Idle_Session_Ready、IEC104_TcpServer_Release_Startup。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Release_Startup(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id)
{
IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
return IEC104_TcpServer_Release_Startup(self->server, identity->generation, activation_id);
}
/**
* 功能:逐站进度只在启用门禁且当前仍闭锁时可读写;已开放后不再补记本轮启动状态。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* activation_id——START活动轮次编号。
* 输出参数:无。
* 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:Idle_Session_Ready先验证归属、FIFO及连接;随后再核对实际START轮次。
* 仅generation相同不足以证明任务有效:STOP/START不换TCP,迟到FINISHED仍可能来自旧轮。
* 不在此检查Type/QOI/TEST或初始化完成,这些业务语义由应用在调用Begin/Complete前确认。
*/
static IEC104_TcpSubmitResult_t Startup_Context_Ready(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id)
{
IEC104_TcpServerStatus_t status;
IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
if (activation_id == 0U || IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK ||
!status.startup_event_gate || !status.startup_pending || status.activation_id != activation_id) {
return IEC104_TCP_SUBMIT_ERROR;
}
return IEC104_TCP_SUBMIT_OK;
}
/**
* 功能:记录本轮计划接受的全站总召尝试;站点使用注册编号,不用可被重新注册复用的CA。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* activation_id——START活动轮次编号。
* station_id——站点编号。
* owner_id——业务所有者编号。
* request_id——请求编号。
* 输出参数:无。
* 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:owner_id为总召模块实例号,request_id为该实例内请求号,二者共同关联迟到的完成通知。
* 本函数不Acquire站点或冻结集合;应用须在整个启动流程持有Lock_Stations。
* OK只表示身份已登记,真正的成功仍须Complete及Query,BEGIN未获准/超时不会自动放行。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Startup_Begin_Station(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id,
uint64_t station_id, uint64_t owner_id, uint64_t request_id)
{
IEC104_Station_t *station;
IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
station = IEC104_Slave_Get_Station_By_Id(self, station_id);
if (station == NULL || !station->_registered || owner_id == 0U || request_id == 0U) {
return IEC104_TCP_SUBMIT_ERROR;
}
/* 同轮已记录成功FINISHED的站保留原请求及票据,即使原票据仍PENDING也不被后来总召覆盖。
* 未完成时允许下一次获准请求替换失败尝试;旧请求随后Complete会因身份不匹配被拒绝。 */
if (station->_startup_activation == activation_id && station->_startup_completed) {
return IEC104_TCP_SUBMIT_OK;
}
station->_startup_activation = activation_id;
station->_startup_owner = owner_id;
station->_startup_request = request_id;
station->_startup_ticket = 0U;
station->_startup_completed = false;
return IEC104_TCP_SUBMIT_OK;
}
/**
* 功能:仅为成功FINISHED登记最终应答的票据,不在这里把“已提交”提升为“已交接”。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* activation_id——START活动轮次编号。
* station_id——站点编号。
* owner_id——业务所有者编号。
* request_id——请求编号。
* completion_ticket——完成应答票据。
* 输出参数:无。
* 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:completion_ticket=0可表示直接HANDED,但本函数不解析事件,调用方必须先核对COMPLETED。
* 即使已记录完成也先验证owner/request;幂等调用保留首张票据,不能以新票据替换旧PENDING。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Startup_Complete_Station(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id,
uint64_t station_id, uint64_t owner_id, uint64_t request_id, uint64_t completion_ticket)
{
IEC104_Station_t *station;
IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
station = IEC104_Slave_Get_Station_By_Id(self, station_id);
if (station == NULL || !station->_registered || owner_id == 0U || request_id == 0U ||
station->_startup_activation != activation_id) { return IEC104_TCP_SUBMIT_ERROR; }
if (station->_startup_owner != owner_id || station->_startup_request != request_id) {
return IEC104_TCP_SUBMIT_ERROR;
}
if (station->_startup_completed) { return IEC104_TCP_SUBMIT_OK; }
station->_startup_ticket = completion_ticket;
station->_startup_completed = true;
return IEC104_TCP_SUBMIT_OK;
}
/**
* 功能:只读汇总当前注册集合:每站须属于本轮、有成功完成记录,且最终应答已经HANDED。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* activation_id——START活动轮次编号。
* 输出参数:无。
* 返回值: 未完成或PENDING返回WAIT,取消/错误票据返回ERROR;
* 说明:调用方用Lock_Stations保持集合稳定;广播和逐CA总召均落到同一份逐站元数据。
* 未完成或PENDING返回WAIT,取消/错误票据返回ERROR;均不清进度、不发送、不自动解除门禁。
* HANDED保证结束帧在后续NORMAL选帧之前进入发送器,不证明写完或主站ACK。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Query_Startup_Stations(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id)
{
IEC104_Station_t *station;
bool any = false;
IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
for (station = self->stations; station != NULL; station = station->_next) {
IEC104_ResponseState_t state;
if (!station->_registered) { continue; }
any = true;
if (station->_startup_activation != activation_id || !station->_startup_completed) {
return IEC104_TCP_SUBMIT_WAIT;
}
state = IEC104_Slave_Get_Response_State(self, station->_startup_ticket);
if (state == IEC104_RESPONSE_PENDING) { return IEC104_TCP_SUBMIT_WAIT; }
if (state != IEC104_RESPONSE_HANDED) { return IEC104_TCP_SUBMIT_ERROR; }
}
/* 空集合没有任何成功总召证据,不能用“全部条件真”直接放行缓存。 */
return any ? IEC104_TCP_SUBMIT_OK : IEC104_TCP_SUBMIT_WAIT;
}
/**
* 功能:不取值、不发送的准入提示;
* 输入参数:self——本模块实例。
* identity——原会话身份。
* reserve——须保留的窗口及记录槽数量。
* priority——优先级。
* 输出参数:无。
* 返回值:按处理分支返回ready、IEC104_TcpServer_Query_Idle_Send_Priority(self->server, identity->generation, reserve, priority)。
* 说明:OK之后应用才构造快照,实际Send仍会重新检查通知。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Query_Idle_Send_Priority(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint16_t reserve,
IEC104_BusinessPriority_t priority)
{
IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
return IEC104_TcpServer_Query_Idle_Send_Priority(self->server, identity->generation, reserve, priority);
}
/**
* 功能:使用默认业务等级查询该事件身份是否允许一次空闲业务发送。
* 输入参数:self/identity——从站服务及事件身份;reserve——提交后须保留的窗口和记录槽数量。
* 输出参数:无。
* 返回值:OK当前可发送;WAIT暂受通知、协议或资源限制;ERROR为身份、参数或状态非法。
* 说明:查询不接手ASDU或预留资源,实际Send_Idle仍重新核对通知和连接状态。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Query_Idle_Send(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint16_t reserve)
{
return IEC104_Slave_Query_Idle_Send_Priority(self, identity, reserve, (IEC104_BusinessPriority_t)0);
}
/**
* 功能:校验容器后重新核对完整会话,不能把此前Query的OK当作预约。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* asdu——ASDU报文。
* reserve——须保留的窗口及记录槽数量。
* priority——优先级。
* 输出参数:self——本模块实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、ready、IEC104_TcpServer_Send_Idle_Priority(self->server, identity->generation, data, length, reserve, priority)。
* 说明:WAIT未保存ASDU;OK由底层SendBuffer接手,后续本地写出和ACK仍通过既有发送记录反映。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Idle_Priority(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint16_t reserve,
IEC104_BusinessPriority_t priority)
{
const uint8_t *data;
uint16_t length;
IEC104_TcpSubmitResult_t ready;
if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) ||
IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
ready = Idle_Session_Ready(self, identity);
if (ready != IEC104_TCP_SUBMIT_OK) { return ready; }
return IEC104_TcpServer_Send_Idle_Priority(self->server, identity->generation, data, length, reserve, priority);
}
/**
* 功能:使用默认业务等级尝试直接发送一帧空闲业务ASDU。
* 输入参数:self/identity——从站服务及事件身份;asdu——待提交原文。
* reserve——提交后须保留的窗口和记录槽数量。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已接手;WAIT尚未接手;ERROR非法;FATAL为连接故障。
* 说明:WAIT不把原文转入队列;待分派通知优先,实际发送仍遵循底层部分写入流程。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Idle(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint16_t reserve)
{
return IEC104_Slave_Send_Idle_Priority(self, identity, asdu, reserve, (IEC104_BusinessPriority_t)0);
}
/**
* 功能:能力属于已Init的服务,不依赖活动连接;
* 输入参数:self——本模块实例。
* capacity——存储容量。
* error——错误诊断。
* 输出参数:capacity——存储容量的更新结果。
* error——错误诊断的更新结果。
* 返回值:按处理分支返回Slave_Error(IEC104_TCP_INVALID_HANDLE, error)、IEC104_TcpServer_Get_Send_Capacity(self->server, capacity, error)。
* 说明:Close后历史ACTIVATED仍可能待分派,须保留INVALID_STATE。
*/
IEC104_TcpResult_t IEC104_Slave_Get_Send_Capacity(const IEC104_Slave_t *self,
IEC104_TcpSendCapacity_t *capacity, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Get_Send_Capacity(self->server, capacity, error);
}
/**
* 功能:使用默认业务等级向请求所属连接提交应答。
* 输入参数:self/identity——从站服务及请求身份;asdu——待提交的应答ASDU。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已复制接手;WAIT未接手;ERROR为身份或ASDU非法;FATAL为连接故障。
* 说明:可直接交接或进入HIGH队列;本入口不返回票据,成功不表示对端已确认。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu)
{
return Submit_Response(self, identity, asdu, NULL);
}
/**
* 功能:使用默认业务等级提交应答,并按需取得交接状态票据。
* 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。
* 输出参数:ticket——可为NULL,仅最终OK时写入。
* 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
* 说明:票据用于Get_Response_State;HANDED仅表示交接,不是对端ACK。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Tracked(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket)
{
return Submit_Response(self, identity, asdu, ticket);
}
/**
* 功能:等级描述业务语义,HIGH生命周期不变;
* 输入参数:self——本模块实例。
* identity——原会话身份。
* asdu——ASDU报文。
* priority——优先级。
* 输出参数:self——本模块实例的更新结果。
* 返回值:返回Submit_Response_Priority(self, identity, asdu, NULL, priority)的结果。
* 说明:兼容模式忽略排序等级,严格模式先排队并受有序直交规则约束。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Priority(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu,
IEC104_BusinessPriority_t priority)
{
return Submit_Response_Priority(self, identity, asdu, NULL, priority);
}
/**
* 功能:按指定业务等级提交应答,并按需取得交接状态票据。
* 输入参数:self/identity——从站服务及请求身份;asdu——应答原文;priority——业务等级,0使用默认值。
* 输出参数:ticket——可为NULL,仅最终OK时写入。
* 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
* 说明:身份与格式检查由共用入口完成;业务等级不改变HIGH应答的连接生命周期。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Tracked_Priority(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket,
IEC104_BusinessPriority_t priority)
{
return Submit_Response_Priority(self, identity, asdu, ticket, priority);
}
/**
* 功能:查询从站服务是否启用了严格业务优先级调度。
* 输入参数:self——从站服务。
* 输出参数:无。
* 返回值:实例有效且底层服务已启用严格模式时为true,否则为false。
* 说明:只读取当前配置,不开启业务周期或改变调度状态。
*/
bool IEC104_Slave_Strict_Priority_Enabled(const IEC104_Slave_t *self)
{
return Slave_Owned(self) && IEC104_TcpServer_Strict_Priority_Enabled(self->server);
}
/**
* 功能:业务轮封装只校验实例并转交传输层;生产者顺序及维护调用由应用负责,
* 输入参数:self——本模块实例。
* 输出参数:self——本模块实例的更新结果。
* 返回值:返回Slave_Owned(self) ? IEC104_TcpServer_Begin_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR的结果。
* 说明:不创建任务、不切换线程,也不根据ASDU类型重新猜测调用方已确定的业务等级。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Begin_Business_Cycle(IEC104_Slave_t *self)
{
return Slave_Owned(self) ? IEC104_TcpServer_Begin_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR;
}
/**
* 功能:设置本轮业务收集的当前等级,授予该等级直接提交的调度资格。
* 输入参数:self——从站服务;priority——当前业务等级。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK设置成功;ERROR为实例、周期状态或等级顺序非法。
* 说明:须处于Begin_Business_Cycle与End_Business_Cycle之间,按高到低的业务顺序推进。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Set_Business_Priority(IEC104_Slave_t *self,
IEC104_BusinessPriority_t priority)
{
return Slave_Owned(self) ? IEC104_TcpServer_Set_Business_Priority(self->server, priority) : IEC104_TCP_SUBMIT_ERROR;
}
/**
* 功能:报告尚未编码但已立即就绪的业务候选,保留其中最高业务等级。
* 输入参数:self——从站服务;priority——当前已就绪候选的有效业务等级。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已登记;ERROR为实例、周期状态或等级非法。
* 说明:用于阻止低等级提前取数或构帧;不预留队列空间,不适用于仍等待外部条件或ACK的业务。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Set_Pending_Business_Priority(IEC104_Slave_t *self,
IEC104_BusinessPriority_t priority)
{
return Slave_Owned(self) ?
IEC104_TcpServer_Set_Pending_Business_Priority(self->server, priority) : IEC104_TCP_SUBMIT_ERROR;
}
/**
* 功能:结束本轮业务收集,关闭当前周期的直接提交资格。
* 输入参数:self——已成功开始业务周期的从站服务。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK结束成功;ERROR为实例无效或当前没有业务周期。
* 说明:不立即排空队列;已报告的待办等级保留到下一轮Begin,Begin成功后须配对调用。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_End_Business_Cycle(IEC104_Slave_t *self)
{
return Slave_Owned(self) ? IEC104_TcpServer_End_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR;
}
/**
* 功能:先检查实例及连接身份,防止旧业务用当前连接的空闲资源通过动作预检。
* 输入参数:self——本模块实例。
* identity——原会话身份。
* asdu_length——ASDU字节长度。
* priority——优先级。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TcpServer_Query_Response_Priority(self->server, identity->generation, asdu_length, priority)。
* 说明:通过只代表当时的容量/阶段预检通过,未锁定容量或票据;后续仍须检查实际提交结果。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Query_Response_Priority(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, uint16_t asdu_length, IEC104_BusinessPriority_t priority)
{
if (!Slave_Owned(self) || identity == NULL || identity->slave != self ||
identity->instance_id != self->serial || identity->generation == 0U) {
return IEC104_TCP_SUBMIT_ERROR;
}
return IEC104_TcpServer_Query_Response_Priority(self->server, identity->generation, asdu_length, priority);
}
/**
* 功能:查询给定事件身份所属连接是否仍有启动业务待完成。
* 输入参数:self/identity——从站服务及事件身份。
* 输出参数:无。
* 返回值:实例、服务身份和连接代次有效且启动仍待完成时为true,否则为false。
* 说明:本函数不推进启动过程,也不解除NORMAL业务暂停。
*/
bool IEC104_Slave_Startup_Is_Pending(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity)
{
return Slave_Owned(self) && identity != NULL && identity->slave == self &&
identity->instance_id == self->serial && identity->generation != 0U &&
IEC104_TcpServer_Startup_Is_Pending(self->server, identity->generation);
}
/**
* 功能:查询应答票据的待交接、已交接或取消状态。
* 输入参数:self——从站服务;ticket——提交应答时取得的交接票据。
* 输出参数:无。
* 返回值:底层票据状态;实例无效时返回ERROR。
* 说明:只查询交接历史;HANDED不等于TCP写完或对端确认,需ACK结果时使用回执接口。
*/
IEC104_ResponseState_t IEC104_Slave_Get_Response_State(const IEC104_Slave_t *self, uint64_t ticket)
{
if (!Slave_Owned(self)) { return IEC104_RESPONSE_ERROR; }
return IEC104_TcpServer_Get_Response_State(self->server, ticket);
}
/**
* 功能:使用局部回执承接底层输出,只有整体提交OK才发布给调用方;
* 输入参数:self——本模块实例。
* identity——原会话身份。
* asdu——ASDU报文。
* receipt——ACK回执。
* priority——优先级。
* 输出参数:self——本模块实例的更新结果。
* receipt——ACK回执的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、result。
* 说明:失败不暴露半份身份/票据。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Acked_Priority(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu,
IEC104_SlaveAckReceipt_t *receipt,
IEC104_BusinessPriority_t priority)
{
const uint8_t *data;
uint16_t length;
IEC104_SlaveAckReceipt_t prepared;
IEC104_TcpSubmitResult_t result;
if (!Slave_Owned(self) || identity == NULL || receipt == NULL || identity->slave != self ||
identity->instance_id != self->serial || identity->generation == 0U || asdu == NULL ||
!Parameters_Compatible(asdu->parameters) ||
IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
memset(&prepared, 0, sizeof(prepared));
prepared.identity = *identity;
result = IEC104_TcpServer_Send_Response_Acked_Priority(self->server, identity->generation, data, length, &prepared.ticket, priority);
if (result == IEC104_TCP_SUBMIT_OK) { *receipt = prepared; }
return result;
}
/**
* 功能:使用默认业务等级提交应答,同时申请可查询对端ACK的回执。
* 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。
* 输出参数:receipt——必填,仅最终OK时写入服务身份、连接代次和票据。
* 返回值:OK已接手并建立观察;WAIT未接手,含观察槽耗尽;ERROR非法;FATAL为连接故障。
* 说明:OK不表示已收到ACK;调用方使用完回执后须调用Release_Ack归还观察资源。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Acked(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu,
IEC104_SlaveAckReceipt_t *receipt)
{
return IEC104_Slave_Send_Response_Acked_Priority(self, identity, asdu, receipt, (IEC104_BusinessPriority_t)0);
}
/**
* 功能:查询是历史通信事实,不要求Check_Request为READY;
* 输入参数:self——本模块实例。
* receipt——ACK回执。
* acked_at_ms——ACK确认毫秒时刻。
* 输出参数:acked_at_ms——ACK确认毫秒时刻的更新结果。
* 返回值:按处理分支返回IEC104_SLAVE_ACK_ERROR、(IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms)。
* 说明:动作提交条件由业务选择相应ACK契约。
*/
IEC104_SlaveAckState_t IEC104_Slave_Get_Ack_State(const IEC104_Slave_t *self,
const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms)
{
if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self ||
receipt->identity.instance_id != self->serial) { return IEC104_SLAVE_ACK_ERROR; }
return (IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Ack_State(self->server,
receipt->identity.generation, receipt->ticket, acked_at_ms);
}
/**
* 功能:历史活动期结果不依赖当前通知是否读空;
* 输入参数:self——本模块实例。
* receipt——ACK回执。
* acked_at_ms——ACK确认毫秒时刻。
* 输出参数:acked_at_ms——ACK确认毫秒时刻的更新结果。
* 返回值:按处理分支返回IEC104_SLAVE_ACK_ERROR、(IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Active_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms)。
* 说明:实例身份仍须匹配,避免静态槽复用混淆回执。
*/
IEC104_SlaveAckState_t IEC104_Slave_Get_Active_Ack_State(const IEC104_Slave_t *self,
const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms)
{
if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self ||
receipt->identity.instance_id != self->serial) { return IEC104_SLAVE_ACK_ERROR; }
return (IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Active_Ack_State(self->server,
receipt->identity.generation, receipt->ticket, acked_at_ms);
}
/**
* 功能:归还回执占用的ACK观察资源,并清空本服务所属的回执。
* 输入参数:self——从站服务;receipt——此前取得的回执,可为NULL。
* 输出参数:receipt——身份属于本服务时清零;空指针、无效实例或外来回执保持不变。
* 返回值:无。
* 说明:释放观察资源不撤销已接手的应答,也不改变已经发生的发送或确认事实。
*/
void IEC104_Slave_Release_Ack(IEC104_Slave_t *self, IEC104_SlaveAckReceipt_t *receipt)
{
if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self ||
receipt->identity.instance_id != self->serial) { return; }
IEC104_TcpServer_Release_Ack(self->server, receipt->identity.generation, receipt->ticket);
memset(receipt, 0, sizeof(*receipt));
}
/**
* 功能:根据已接收的有效I帧请求构造否定应答,并提交到该请求所属连接。
* 输入参数:self——从站服务;event——有效请求事件;cause——44..49,表示未知字段或遥控软压板/时间戳错误。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已接手应答;WAIT暂未接手;ERROR为事件、原因或状态非法;FATAL为连接故障。
* 说明:在局部缓冲构造副本并置否定标志,不修改原请求;待分派的连接状态通知会阻止提交。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Reject_Request(IEC104_Slave_t *self,
const IEC104_SlaveEvent_t *event, int cause)
{
uint8_t bytes[IEC104_MAX_ASDU_LEN];
const uint8_t *data;
uint16_t length, reply_length;
IEC60870_Asdu_t reply;
IEC104_SlaveEventIdentity_t identity;
IEC104_TcpServerStatus_t status;
if (cause < IEC60870_ASDU_COT_UNKNOWN_TYPE || cause > IEC60870_ASDU_COT_COMMAND_TIME_ERROR ||
!IEC104_Slave_Get_Event_Identity(self, event, &identity) ||
event->transport.type != IEC104_TCP_EVENT_I_FRAME || event->asdu_result != IEC60870_ASDU_OK ||
IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
/* 本次事件之后尚未消费的启停通知表明链路已停用或曾停用,不能跨启停提交应答。 */
if (status.pending_state_event_count != 0U ||
IEC60870_Asdu_Get_Data(&event->asdu, &data, &length) != IEC60870_ASDU_OK ||
IEC60870_Asdu_Build_Response(&parameters104, data, length, cause, 1,
bytes, sizeof(bytes), &reply_length) != IEC60870_ASDU_OK ||
IEC60870_Asdu_Create_From_Buffer(&reply, &parameters104, bytes, reply_length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
return Submit_Response(self, &identity, &reply, NULL);
}
/**
* 功能:把应答交给产生该事件的原服务、原会话。
* 输入参数:connection——事件内已绑定的接口;asdu——布局兼容的完整ASDU,可独立于接收视图。
* 输出参数:ticket——应答交接票据的更新结果。
* 返回值:透传OK/WAIT/ERROR/FATAL并记录在原事件中;普通send_asdu包装为bool。
* 说明:先检查Slave所有权和serial,再由TcpServer检查generation、启停状态及发送容量。
* OK表示已复制接手,不代表写完或收到ACK;WAIT未接手,业务保存原事件/ASDU后择机重试。
* 不查找当前新连接来替换旧身份;FATAL可能已经写出字节,不能作为未发送直接重放。
*/
static IEC104_TcpSubmitResult_t Submit_ASDU(IEC60870_MasterConnection_t *connection,
const IEC60870_Asdu_t *asdu, uint64_t *ticket)
{
IEC104_SlaveEvent_t *event = Get_Context(connection);
IEC104_SlaveEventIdentity_t identity;
if (event == NULL) { return IEC104_TCP_SUBMIT_ERROR; }
identity.slave = event->_owner;
identity.instance_id = event->_owner_serial;
identity.generation = event->_generation;
event->_last_submit_result = Submit_Response(event->_owner, &identity, asdu, ticket);
return event->_last_submit_result;
}
/**
* 功能:将共用主站连接接口的布尔发送调用转换为从站应答提交。
* 输入参数:connection——绑定从站事件的共用连接接口;asdu——待提交ASDU。
* 输出参数:无。
* 返回值:底层返回SUBMIT_OK时为true,等待或任何错误均为false。
* 说明:复用Submit_ASDU完成事件身份检查和结果记录;true仅表示已接手。
*/
static bool Send_ASDU(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu)
{
return Submit_ASDU(connection, asdu, NULL) == IEC104_TCP_SUBMIT_OK;
}
/**
* 功能:104专用带凭证入口;
* 输入参数:connection——连接对象。
* asdu——ASDU报文。
* ticket——应答交接票据。
* 输出参数:ticket——应答交接票据的更新结果。
* 返回值:返回Submit_ASDU(connection, asdu, ticket)的结果。
* 说明:与共用连接接口采用相同的HIGH FIFO发送策略。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Send_ASDU_Tracked(
IEC60870_MasterConnection_t *connection, const IEC60870_Asdu_t *asdu, uint64_t *ticket)
{
return Submit_ASDU(connection, asdu, ticket);
}
/**
* 功能:修改ASDU的传送原因和否定标志,再沿原连接提交确认或终止。
* 输入参数:cause——目标COT;negative——目标P/N;asdu——允许原地修改的ASDU。
* 输出参数:asdu——按顺序设置COT与P/N;connection所属事件记录本次提交结果。
* 取得有效事件后即更新提交结果;后续失败不回滚已完成的ASDU修改。
* 返回值:true已接手;false表示字段修改或提交失败,详细提交结果保存在事件中。
* 说明:按COT、P/N顺序修改,后续失败不回滚已经成功的修改;不执行业务,也不自动重试。
*/
static bool Send_Confirmation(IEC60870_MasterConnection_t *connection,
IEC60870_Asdu_t *asdu, int cause, bool negative)
{
IEC104_SlaveEvent_t *event = Get_Context(connection);
if (event == NULL) { return false; }
event->_last_submit_result = IEC104_TCP_SUBMIT_ERROR;
if (IEC60870_Asdu_Set_COT(asdu, cause) != IEC60870_ASDU_OK ||
IEC60870_Asdu_Set_Negative(asdu, negative ? 1 : 0) != IEC60870_ASDU_OK) {
return false;
}
return Send_ASDU(connection, asdu);
}
/**
* 功能:共用激活确认入口:COT=7,P/N由业务指定;
* 输入参数:connection——连接对象。
* asdu——ASDU报文。
* negative——否定确认标志。
* 输出参数:asdu——COT改为7并设置P/N;connection所属事件记录提交结果。
* 沿用Send_Confirmation的修改顺序,失败不回滚已经完成的字段修改。
* 返回值:激活确认被发送层接手返回true;WAIT、非法请求或发送故障返回false。
* 说明:沿用Send_Confirmation的修改及提交契约。
*/
static bool Send_ACT_CON(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu, bool negative)
{
return Send_Confirmation(connection, asdu, IEC60870_ASDU_COT_ACTIVATION_CON, negative);
}
/**
* 功能:共用激活终止入口:COT=10、P/N=0;
* 输入参数:connection——连接对象。
* asdu——ASDU报文。
* 输出参数:asdu——COT改为10且P/N清零;connection所属事件记录提交结果。
* 沿用Send_Confirmation的修改顺序,失败不回滚已经完成的字段修改。
* 返回值:激活终止被发送层接手返回true;WAIT、非法请求或发送故障返回false。
* 说明:由业务处理完成后调用,不自动跟随ACT_CON发送。
*/
static bool Send_ACT_TERM(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu)
{
return Send_Confirmation(connection, asdu, IEC60870_ASDU_COT_ACTIVATION_TERMINATION, false);
}
/**
* 功能:共用参数查询入口:有效事件接口返回静态只读参数;
* 输入参数:connection——连接对象。
* 输出参数:无。
* 返回值:共用参数查询入口:有效事件接口返回静态只读参数;
* 说明:不要求原连接仍在线,也不表示可以发送。
*/
static const IEC60870_AppLayerParameters_t *Get_Parameters(IEC60870_MasterConnection_t *connection)
{
return Get_Context(connection) != NULL ? &parameters104 : NULL;
}
/**
* 功能:让目标事件的ASDU视图和共用发送接口指向目标自身的存储。
* 输入参数:event——事件。
* 输出参数:event->asdu/connection/asdu_result;不改来源身份、原文和历史提交结果。
* 返回值:无。
* 说明:前提:transport原文已复制完毕,事件地址在后续使用期间保持稳定。
* 非I帧不提供ASDU接口;I帧视图构造失败时保留原通知供诊断,connection保持清零。
* 视图借用本事件中APCI之后的ASDU字节,不再借用TcpServer或Receiver的内部缓冲。
*/
static void Bind_Event(IEC104_SlaveEvent_t *event)
{
uint16_t length;
memset(&event->asdu, 0, sizeof(event->asdu));
memset(&event->connection, 0, sizeof(event->connection));
event->asdu_result = IEC60870_ASDU_UNSUPPORTED;
if (event->transport.type != IEC104_TCP_EVENT_I_FRAME) { return; }
event->asdu_result = IEC60870_ASDU_ERROR;
length = event->transport.data.i_frame.apdu_length;
if (length < IEC104_APCI_LEN || length > IEC104_MAX_APDU_LEN) { return; }
event->asdu_result = IEC60870_Asdu_Create_From_Buffer(&event->asdu, &parameters104,
event->transport.data.i_frame.apdu + IEC104_APCI_LEN, (uint16_t)(length - IEC104_APCI_LEN));
if (event->asdu_result != IEC60870_ASDU_OK) { return; }
event->connection.object = event;
event->connection.send_asdu = Send_ASDU;
event->connection.send_act_con = Send_ACT_CON;
event->connection.send_act_term = Send_ACT_TERM;
event->connection.get_application_layer_parameters = Get_Parameters;
}
/**
* 功能:从静态池取得一个Slave,并为它取得一个私有TcpServer。
* 输入参数:无。
* 输出参数:无。
* 返回值:成功返回不透明句柄;任一池无可用槽或身份编号耗尽时返回NULL。
* 说明:不创建socket、不分配堆内存;只有取得底层服务后才占用Slave槽并递增serial。
* 成功后由业务配对Destroy;不能自行分配、复制、清零或free句柄指向的对象。
*/
IEC104_Slave_t *IEC104_Slave_Create(void)
{
size_t index;
for (index = 0U; index < IEC104_TCP_SERVER_CAPACITY; ++index) {
IEC104_Slave_t *self = &slave_pool[index];
if (self->server == NULL && self->serial != UINT64_MAX) {
IEC104_TcpServer_t *server = IEC104_TcpServer_Create();
if (server == NULL) { return NULL; }
self->server = server;
++self->serial;
return self;
}
}
return NULL;
}
/**
* 功能:归还已关闭且通知已读空的Slave及其底层服务。
* 输入参数:self——Create取得且未Destroy的句柄;error——可选的本次调用诊断。
* 输出参数:self——本模块实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK时句柄失效;运行中为INVALID_STATE,通知未读空为EVENTS_PENDING,失败保留对象。
* 说明:先由TcpServer检查并归还底层槽,再释放Slave槽;保留serial隔离旧事件。
* 常规顺序为Close -> NextEvent读空 -> Destroy;尚未Init或Init失败后也可直接归还。
*/
IEC104_TcpResult_t IEC104_Slave_Destroy(IEC104_Slave_t *self, IEC104_TcpError_t *error)
{
IEC104_TcpResult_t result;
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
if (self->stations != NULL || self->station_locks != 0U || self->station_snapshots != 0U) {
return Slave_Error(IEC104_TCP_INVALID_STATE, error);
}
result = IEC104_TcpServer_Destroy(self->server, error);
if (result == IEC104_TCP_OK) { self->server = NULL; }
return result;
}
/**
* 功能:初始化所拥有的TCP服务,开始监听并建立服务级发送队列。
* 输入参数:self——有效Slave句柄;config——本次监听和协议配置,底层复制后使用。
* 输出参数:error——本次诊断,允许NULL;底层返回的阶段和网络错误保持原样。
* 返回值:OK已监听,其他结果区分参数、配置、生命周期或网络失败。
* 说明:成功不表示已有主站,之后必须驱动Poll或Prepare/Process;失败不销毁句柄。
* 再次Init前须Close并读空旧通知,旧事件的连接身份不会因重新初始化而更新。
*/
IEC104_TcpResult_t IEC104_Slave_Init(IEC104_Slave_t *self,
const IEC104_SlaveConfig_t *config, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Init(self->server, config, error);
}
/**
* 功能:为外部事件循环查询socket关注集合、等待期限及本地待处理工作。
* 输入参数:self——已Init的服务;info——非NULL快照存储;error——可选诊断。
* 输出参数:info——查询信息的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK时写出info;失败保持info不变,不进行收发或协议推进。
* 说明:有待消费事件或need_process时不得阻塞等待;状态改变后须重新Prepare。
* 快照中的socket仅供注册,所有权仍属于内部TcpServer,业务不能直接读写或关闭。
*/
IEC104_TcpResult_t IEC104_Slave_Prepare(const IEC104_Slave_t *self,
IEC104_TcpWaitInfo_t *info, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Prepare(self->server, info, error);
}
/**
* 功能:把外部事件循环的一批就绪、定时或本地通知交给底层有界推进。
* 输入参数:self——已Init的服务;ready——必填就绪批次,身份来自对应Prepare/注册快照。
* 输出参数:error——可选诊断;返回值与TcpServer_Process一致,OK也包括没有进展。
* 返回值:返回值与TcpServer_Process一致,OK也包括没有进展。
* 返回后消费NextEvent,再Prepare更新关注集合。
* 说明:不等待;返回后消费NextEvent,再Prepare更新关注集合。旧通知不得替换为新token。
* 客户端故障通过收尾事件交付,服务级失败则由调用方保存诊断后Close。
*/
IEC104_TcpResult_t IEC104_Slave_Process(IEC104_Slave_t *self,
const IEC104_TcpReady_t *ready, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Process(self->server, ready, error);
}
/**
* 功能:独立主循环使用的准备、至多一次网络等待和有界推进组合入口。
* 输入参数:self——已Init的服务;max_wait_ms——本轮网络等待上限,0不等待;error可为NULL。
* 输出参数:self——本模块实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK表示服务可继续;客户端断线不一定使本函数失败,须读取NextEvent。
* 说明:等待还受协议期限和本地工作约束;max_wait_ms不保证整个函数的执行耗时。
* 不创建后台线程、不调用业务处理函数;每轮返回后由应用消费通知。
*/
IEC104_TcpResult_t IEC104_Slave_Poll(IEC104_Slave_t *self,
uint32_t max_wait_ms, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Poll(self->server, max_wait_ms, error);
}
/**
* 功能:取出最早的TCP通知,并为有效I帧建立ASDU视图和原连接的发送接口。
* 输入参数:self——有效句柄,Close后仍可读取;event——地址稳定的非NULL输出存储。
* 输出参数:self——本模块实例的更新结果。
* event——事件的更新结果。
* 返回值:READY替换整个event;EMPTY/ERROR保持上次事件及其视图不变。
* 说明:先读入临时量,只有取得通知后才覆盖输出;保存原服务serial和连接generation。
* READY仅表示取得事件,I帧还须检查asdu_result;视图失败仍保留原文,不自动确认。
* 不进行I/O;下一次READY会覆盖同一event,延迟处理须另存并调用Copy_Event修复自引用。
*/
IEC104_TcpEventResult_t IEC104_Slave_NextEvent(IEC104_Slave_t *self, IEC104_SlaveEvent_t *event)
{
IEC104_TcpEvent_t received;
IEC104_TcpEventResult_t result;
if (!Slave_Owned(self) || event == NULL) { return IEC104_TCP_EVENT_ERROR; }
result = IEC104_TcpServer_NextEvent(self->server, &received);
if (result != IEC104_TCP_EVENT_READY) { return result; }
memset(event, 0, sizeof(*event));
event->transport = received;
event->_owner = self;
event->_owner_serial = self->serial;
event->_generation = received.generation;
event->_last_submit_result = IEC104_TCP_SUBMIT_ERROR;
Bind_Event(event);
return IEC104_TCP_EVENT_READY;
}
/**
* 功能:只校验事件自身布局和自引用,不要求原服务或TCP会话仍存活。
* 输入参数:event——事件。
* 输出参数:无。
* 返回值:事件身份字段、类型和适用的ASDU自引用一致时返回true,否则false。
* 说明:Copy_Event允许保存历史原文;Get_Event_Identity在此基础上额外校验当前服务实例。
* 解析失败的I帧仍是有效通知,由业务处理其asdu_result,不在此丢弃诊断信息。
*/
static bool Event_Valid(const IEC104_SlaveEvent_t *event)
{
const uint8_t *data;
uint16_t length;
if (event == NULL || event->_owner == NULL || event->_owner_serial == 0U ||
event->_generation == 0U || event->_generation != event->transport.generation ||
event->transport.type < IEC104_TCP_EVENT_CONNECTED ||
event->transport.type > IEC104_TCP_EVENT_DEACTIVATED) {
return false;
}
if (event->transport.type == IEC104_TCP_EVENT_I_FRAME && event->asdu_result == IEC60870_ASDU_OK) {
if (event->connection.object != event || Get_Context(&event->connection) != event ||
event->asdu.parameters != &parameters104 ||
IEC60870_Asdu_Get_Data(&event->asdu, &data, &length) != IEC60870_ASDU_OK ||
data != event->transport.data.i_frame.apdu + IEC104_APCI_LEN ||
(uint32_t)length + IEC104_APCI_LEN != event->transport.data.i_frame.apdu_length) {
return false;
}
}
return true;
}
/**
* 功能:把事件复制到稳定的目标存储,同时重建目标ASDU视图及发送接口的自引用。
* 输入参数:source——NextEvent或本函数产生的有效事件;destination——目标事件存储。
* 输出参数:destination——目标存储的更新结果。
* 返回值:true已复制或源/目标为同一合法对象;false校验失败且不修改目标。
* 说明:先核对源视图仍借用源原文,避免传播普通赋值形成的悬空绑定。
* 保留原服务、代次和最近提交结果,不查询当前主站、不发送;历史事件也可复制保存。
* 复制只延长原文和接口存储的寿命,不能使已关闭或已被替换的原连接重新可用。
*/
bool IEC104_Slave_Copy_Event(IEC104_SlaveEvent_t *destination, const IEC104_SlaveEvent_t *source)
{
if (destination == NULL || !Event_Valid(source)) { return false; }
if (destination != source) { *destination = *source; Bind_Event(destination); }
return true;
}
/**
* 功能:验证业务收到的Slave事件,交付可保存的服务实例和原连接身份。
* 输入参数:self为所属服务;event为原事件或Copy_Event副本;identity为非NULL输出。
* 输出参数:identity——原会话身份的更新结果。
* 返回值:true写出身份;false为非法来源/布局/视图或参数,保持输出不变。
* 说明:只匹配服务实例,不用当前TCP代次拒绝历史通知;是否仍可推进另由Check_Request判断。
*/
bool IEC104_Slave_Get_Event_Identity(const IEC104_Slave_t *self,
const IEC104_SlaveEvent_t *event, IEC104_SlaveEventIdentity_t *identity)
{
IEC104_SlaveEventIdentity_t copy;
if (!Slave_Owned(self) || identity == NULL || !Event_Valid(event) ||
event->_owner != self || event->_owner_serial != self->serial) {
return false;
}
memset(&copy, 0, sizeof(copy));
copy.slave = self;
copy.instance_id = event->_owner_serial;
copy.generation = event->_generation;
*identity = copy;
return true;
}
/**
* 功能:统一判断业务是否应先处理通知、放弃失效请求,或继续当前会话的工作。
* 输入参数:identity为Get_Event_Identity的只读结果,允许零初始化表示尚未绑定会话。
* 输出参数:无。
* 返回值:ERROR为参数/查询失败;WAIT_EVENTS优先于会话判断;STALE为原身份不再可用;READY可继续。
* 说明:检查通知FIFO、服务实例、TCP代次和传输激活状态,不执行I/O或保留发送窗口。
* 先读空通知可避免同一代次STOP后又START时,仅凭最终激活状态误续旧业务。
*/
IEC104_SlaveRequestState_t IEC104_Slave_Check_Request(const IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity)
{
IEC104_TcpServerStatus_t status;
if (!Slave_Owned(self) || identity == NULL ||
IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK) {
return IEC104_SLAVE_REQUEST_ERROR;
}
if (status.pending_event_count != 0U) { return IEC104_SLAVE_REQUEST_WAIT_EVENTS; }
if (identity->slave != self || identity->instance_id != self->serial ||
identity->generation == 0U || identity->generation != status.generation ||
!status.connected || !status.connection_status_valid || !status.connection.data_transfer_started) {
return IEC104_SLAVE_REQUEST_STALE;
}
return IEC104_SLAVE_REQUEST_READY;
}
/**
* 功能:补充共用发送接口bool结果,查询这个事件连接最近一次提交的具体状态。
* 输入参数:connection——event.connection的地址;不是Slave句柄,也不是底层socket。
* 输出参数:无。
* 返回值:OK/WAIT/ERROR/FATAL;尚未发送或接口绑定无效时返回ERROR。
* 说明:记录只在提交时更新,不随后续Poll或主站ACK更新;发送完成事实应查看RECORD事件。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Get_Last_Submit_Result(
const IEC60870_MasterConnection_t *connection)
{
const IEC104_SlaveEvent_t *event = Get_Context(connection);
return event != NULL ? event->_last_submit_result : IEC104_TCP_SUBMIT_ERROR;
}
/**
* 功能:取得本接入使用的104应用层参数,供业务构造主动上报或独立应答ASDU。
* 输入参数:self——有效Slave句柄,不要求已Init或当前在线。
* 输出参数:无。
* 返回值:静态只读参数地址;无效句柄返回NULL,调用方不能修改或释放该参数。
* 说明:内部调用:Slave_Owned。
*/
const IEC60870_AppLayerParameters_t *IEC104_Slave_Get_Application_Layer_Parameters(
const IEC104_Slave_t *self)
{
return Slave_Owned(self) ? &parameters104 : NULL;
}
/**
* 功能:校验ASDU布局后复制到服务级NORMAL队列,用于主动上报。
* 输入参数:self——已Init的服务;asdu——合法且与104布局兼容的ASDU,不包含APCI。
* priority——0沿用事件级4,显式1..12由生产者按业务指定;本入口不按Type猜测故障级6。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已复制,WAIT未接手可重试,ERROR参数/状态非法,FATAL底层队列异常。
* 说明:允许首次接入前及断线期间缓存,本次不直接写socket;空间不足可覆盖最旧NORMAL。
* Close清空缓存;重连恢复可能重复,业务应按自身语义处理。请求应答使用事件connection。
* 等级只决定严格模式的候选次序,不改变NORMAL覆盖、离线缓存及启动门禁规则。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Event_Priority(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu,
IEC104_BusinessPriority_t priority)
{
const uint8_t *data;
uint16_t length;
if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) ||
IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
return IEC104_TcpServer_Enqueue_Event_Priority(self->server, data, length, priority);
}
/**
* 功能:使用默认业务等级将主动事件复制到服务级NORMAL队列。
* 输入参数:self——从站服务;asdu——待排队的事件ASDU。
* 输出参数:self——本模块实例的更新结果。
* 返回值:OK已接手;WAIT暂时无法接手;ERROR为实例或输入非法;FATAL为队列状态故障。
* 说明:事件不绑定请求身份,可在无活动连接时缓存;成功不表示已经发送。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Event(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu)
{
return IEC104_Slave_Enqueue_Event_Priority(self, asdu, (IEC104_BusinessPriority_t)0);
}
/**
* 功能:将单对象Type30/31、COT3遥信交给本从站的独立SOE区。
* 输入参数:self/asdu——从站和标准104原文;priority——业务等级;deferred——是否暂缓;ticket——可选身份输出。
* 输出参数:ticket仅在接手成功时写入;deferred为true时不可为空。
* 返回值:底层OK/WAIT/ERROR/FATAL;无效从站或ASDU返回ERROR。
* 说明:不借用调用方原文,普通遥测不占SOE额度;成功不代表主站已确认。
*/
IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Soe(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu,
IEC104_BusinessPriority_t priority, bool deferred, IEC104_SoeTicket_t *ticket)
{
const uint8_t *data;
uint16_t length;
if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) ||
IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) {
return IEC104_TCP_SUBMIT_ERROR;
}
return IEC104_TcpServer_Enqueue_Soe(self->server, data, length, priority, deferred, ticket);
}
/**
* 功能:发布或取消本从站先前保存的SOE补报占位。
* 输入参数:self——原从站;ticket——入队身份;publish——发布或取消。
* 输出参数:无。
* 返回值:无效从站返回INVALID_HANDLE;其余返回底层处理结果。
* 说明:只处理仍存在的原占位;覆盖、筛选清除或关闭后不得创建替代事件。
*/
IEC104_TcpResult_t IEC104_Slave_Resolve_Soe(IEC104_Slave_t *self,
const IEC104_SoeTicket_t *ticket, bool publish)
{
if (!Slave_Owned(self)) { return IEC104_TCP_INVALID_HANDLE; }
return IEC104_TcpServer_Resolve_Soe(self->server, ticket, publish);
}
/**
* 功能:事件分类只在Slave集中映射;底层队列按固定104布局匹配CA与Type,不解释对象。
* 输入参数:kind——类别。
* bitmap——位图。
* 输出参数:bitmap——位图的更新结果。
* 返回值:按处理分支返回0、1。
* 说明:这里不查站点表:队列没有station_id,不能区分同CA历次注册留下的原文。
* SystemCommand在调用前负责检查受理时的站点仍注册,并在应用侧清除相同CA的待发事件。
*/
static int Event_Class_Bitmap(IEC104_SlaveEventClass_t kind, uint8_t bitmap[32])
{
unsigned type;
if (kind != IEC104_SLAVE_EVENTS_TIME_TAGGED) { return 0; }
memset(bitmap, 0, 32U);
for (type = 30U; type <= 40U; ++type) { bitmap[type / 8U] |= (uint8_t)(1U << (type % 8U)); }
return 1;
}
/**
* 功能:按公共地址和事件类别统计尚未提交为I帧的NORMAL事件。
* 输入参数:self——从站服务;common_address——目标站点公共地址;kind——支持的事件类别。
* 输出参数:count——成功时的匹配数量;error——可选诊断。
* 返回值:OK统计成功;INVALID_HANDLE/INVALID_ARGUMENT为本层校验失败,其余错误由底层返回。
* 说明:当前类别筛选为带时标事件;已编号或等待ACK的帧不计入,也不校验当前站点注册关系。
*/
IEC104_TcpResult_t IEC104_Slave_Count_Pending_Events(const IEC104_Slave_t *self,
uint16_t common_address, IEC104_SlaveEventClass_t kind, uint32_t *count, IEC104_TcpError_t *error)
{
uint8_t bitmap[32];
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
if (!Event_Class_Bitmap(kind, bitmap)) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); }
return IEC104_TcpServer_Count_Pending_Normal(self->server, common_address, bitmap, count, error);
}
/**
* 功能:按公共地址和事件类别丢弃尚未提交为I帧的NORMAL事件。
* 输入参数:self——从站服务;common_address——目标站点公共地址;kind——支持的事件类别。
* 输出参数:removed——成功时的删除数量;error——可选诊断。
* 返回值:OK删除完成;INVALID_HANDLE/INVALID_ARGUMENT为本层校验失败,其余错误由底层返回。
* 说明:只删除未编号候选,不撤销在途或等待ACK的帧;站点归属由调用业务自行核对。
*/
IEC104_TcpResult_t IEC104_Slave_Discard_Pending_Events(IEC104_Slave_t *self,
uint16_t common_address, IEC104_SlaveEventClass_t kind, uint32_t *removed, IEC104_TcpError_t *error)
{
uint8_t bitmap[32];
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
if (!Event_Class_Bitmap(kind, bitmap)) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); }
return IEC104_TcpServer_Discard_Pending_Normal(self->server, common_address, bitmap, removed, error);
}
/**
* 功能:读取当前主站的IPv4、源端口和连接代次副本,不执行网络查询。
* 输入参数:self——已Init的服务;peer——非NULL输出存储;error——可选诊断。
* 输出参数:peer——对端信息的更新结果。
* error——错误诊断的更新结果。
* 返回值:仅OK写peer;无当前连接为NOT_CONNECTED,其他失败也保持peer原值。
* 说明:这是当前状态;历史事件的地址应从事件自身读取,不能用新主站地址替代旧来源。
*/
IEC104_TcpResult_t IEC104_Slave_Get_Remote_Address(const IEC104_Slave_t *self,
IEC104_TcpPeerInfo_t *peer, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Get_Remote_Address(self->server, peer, error);
}
/**
* 功能:按事件捕获的原连接身份主动断开主站,保留监听和服务级NORMAL。
* 输入参数:self——所属Slave;event——本服务事件或Copy_Event副本;error——可选诊断。
* 输出参数:self——本模块实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK已断开;其他服务/已复用Slave的事件为INVALID_ARGUMENT;当前无连接为NOT_CONNECTED;
* 仍有连接但代次不同为STALE_GENERATION;底层服务异常通过原结果和error返回。
* 说明:来源serial先由本层检查,原generation再由TcpServer核对;不用当前代次代替旧身份。
* 不等待STOPDT或ACK,成功后继续读取收尾事件,再Prepare更新监听条件。
*/
IEC104_TcpResult_t IEC104_Slave_Close_Connection(IEC104_Slave_t *self,
const IEC104_SlaveEvent_t *event, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
if (event == NULL || event->_owner != self || event->_owner_serial != self->serial ||
event->_generation == 0U) {
return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error);
}
return IEC104_TcpServer_Close_Connection(self->server, event->_generation, error);
}
/**
* 功能:紧凑业务上下文只需保留来源身份即可关闭原会话;
* 输入参数:self——本模块实例。
* identity——原会话身份。
* error——错误诊断。
* 输出参数:self——本模块实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:按处理分支返回Slave_Error(IEC104_TCP_INVALID_HANDLE, error)、Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error)、IEC104_TcpServer_Close_Connection(self->server, identity->generation, error)。
* 说明:校验与完整事件关闭入口一致。
*/
IEC104_TcpResult_t IEC104_Slave_Close_Connection_By_Identity(IEC104_Slave_t *self,
const IEC104_SlaveEventIdentity_t *identity, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
if (identity == NULL || identity->slave != self || identity->instance_id != self->serial ||
identity->generation == 0U) {
return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error);
}
return IEC104_TcpServer_Close_Connection(self->server, identity->generation, error);
}
/**
* 功能:取得内部TCP服务、队列和最近会话的状态副本,不推进协议或消费队列。
* 输入参数:self——有效句柄;status——非NULL输出存储;error——可选诊断。
* 输出参数:status——状态快照的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK写入status,失败保持输出;Create后、Init失败后和Close后均可查询。
* 说明:会话和队列各自有有效标志,connected与data_transfer_started含义不同。
*/
IEC104_TcpResult_t IEC104_Slave_Get_Status(const IEC104_Slave_t *self,
IEC104_TcpServerStatus_t *status, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Get_Status(self->server, status, error);
}
/**
* 功能:关闭监听和当前连接,清空待发ASDU,但保留已生成的业务及收尾通知。
* 输入参数:self——尚未Destroy的句柄;error——可选的本次调用诊断。
* 输出参数:self——本模块实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK已收尾或本来未初始化;无效句柄、重入按底层约定返回错误。
* 说明:不等待业务发送/ACK,不归还对象池名额;读空事件后可重新Init或Destroy。
* 自建事件循环还须撤销旧socket注册和定时器,不能将其通知用于下一次Init。
*/
IEC104_TcpResult_t IEC104_Slave_Close(IEC104_Slave_t *self, IEC104_TcpError_t *error)
{
if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); }
return IEC104_TcpServer_Close(self->server, error);
}