libIEC61850 Open source学习心得（二）—— Client注册报告控制块

报告服务是IEC61850进行数据交互的重要手段，libIEC61850提供了较为全面的报告手段，包括：数据变化、品质 变化、数据更新、周期性以及总召，基本涵盖了61850标准中的要求。

一、常用ClientReportControl API

1. ClientReportControlBlock  IedConnection_getRCBValues(IedConnection self, IedClientError* error, char* rcbReference, ClientReportControlBlock updateRcb)

获取服务端指定报告控制块信息，并将信息返回至 ClientReportControlBlock 对象。输入参数中要注意rcbReference， 该参数是该报告控制块的引用字符串信息，由:IEDName + LDevice inst + / + LLN0 + . + buffeded + . + report control name. 其中要注意buffered，如果该报告控制块是unbuffered，就用"RP"表示，如果是buffered，就用BR表示，例如官方服务端例子server_example3中的报告控制块就可以表示为"simpleIOGenericIO/LLN0.RP.EventsRCB".

2. void  IedConnection_installReportHandler(IedConnection self, char* rcbReference, char* rptId, ReportCallbackFunction handler, void* handlerParameter)

注册报告控制块的处理程序，其中rptId可以通过ClientReportControlBlock_getRptId(ClientReportControlBlock )函数获得，也可以通过解析出ICD文件中rptID属性获得；ReportCallbackFunction handler是当客户端收到服务端报告时的回调函数， ReportCallbackFunction 是一个 void  (void * parameter, ClientReport report)类型的函数指针，parameter是需要传入的参数，report是收到的报告信息，里面包含了数据值、时标等信息。

3. void ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, int trgOps)

设置报告的触发条件，使用TRG_OPT_DATA_CHANGED，TRG_OPT_QUALITY_CHANGED，TRG_OPT_DATA_UPDATE，TRG_OPT_INTEGRITY，TRG_OPT_GI宏设置条件参数，中间可以使用 or 运算设置多个触发条件。

4. void ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool rptEna)

使能报告控制块。

5. void ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd)

设置周期性上报时的周期值，以毫秒（ms）为单位。

6. void  IedConnection_setRCBValues(IedConnection self, IedClientError* error, ClientReportControlBlock rcb, uint32_t parametersMask, bool singleRequest)

设置报告控制块参数，获取到的报告控制块可以通过该方法设置参数，parameterMask可以通过RCB_ELEMENT_系列宏设置相关参数，由于该函数我还不是太深入理解，在此不作太多说明，待以后补完。

7. void ClientReportControlBlock_setGI(ClientReportControlBlock self, bool gi)

使能总召报告。

8. MmsValue* ClientReport_getDataSetValues(ClientReport self)

获取报告中的数据值。报告控制块是和数据集(DataSet)关联的，因此这里获取到的MmsValue是整个数据集的数据集合，可以通过MmsValue_getElement(MmsValue *)函数获取其中的数据对象(DO)或者数据属性(DA)。

这里有个吐槽的地方，就是这里获取到的MmsValue是不包含DA或者DO的Reference的，因此如果没有获取数据集信息，就无法分辨是哪一个数据，好在无论任何情况下返回的报告总是按照数据集里的DO或者DA的索引进行排序的，通过这里的索引和获取到的数据集索引进行匹配，就可以分辨每个数据。

注：由于存在上面这个问题，因此最好是使用IedConnection_getDataSetDirectory()方法获取服务端实时的数据集信息，而不是通过解析ICD文件获取，因为ICD文件中的顺序和名称很有可能是错误的。

9. ReasonForInclusion ClientReport_getReasonForInclusion(ClientReport self, int elementIndex)

获取报告原因。报告原因就是包括了上面提到的5种触发条件。elementIndex就是DO或者DA数据集中的索引。

二、使用方法

1. 注册报告控制块

/*创建连接*/
IedClientError error;
IedConnection con = IedConnection_create();
IedConnection_connect(con, &error, hostname, tcpPort);

/*获取RCB的信息*/
ClientReportControlBlock rcb = IedConnection_getRCBValues(con,&error,"simpleIOGenericIO/LLN0.RP.EventRCB", NULL);

/*获取服务端的实时数据集信息*/
ClientDataSet clientDataSet = IedConnection_readDataSetValues(con, &error, "simpleIOGenericIO/LLN0$Events", NULL);

if (clientDataSet == NULL)
    printf("failed to read dataset\n");

bool deletable;
/*获取数据集列表，这里要用LinkedList，顺序不能错误，不然在回调函数中匹配的数据信息就是错误的*/
LinkedList list = IedConnection_getDataSetDirectory(con,&error,"simpleIOGenericIO/LLN0$Events",&deletable);

/*注册收到报告时的回调函数*/
IedConnection_installReportHandler(con, "simpleIOGenericIO/LLN0.RP.EventRCB", ClientReportControlBlock_getRptId(rcb), reportCallbackFunction, (void *)list);

/*设置报告的触发参数，这里设置了周期性上报和数据改变时上报*/
ClientReportControlBlock_setTrgOps(rcb, TRG_OPT_INTEGRITY | TRG_OPT_DATA_CHANGED);
/*设置报告的触发参数，使能报告控制块*/
ClientReportControlBlock_setRptEna(rcb, true);
/*设置报告的触发参数，设置周期性报告周期，这里设置为5000毫秒上报一次*/
ClientReportControlBlock_setIntgPd(rcb, 5000);
/*设置报告控制块参数*/
IedConnection_setRCBValues(con, &error, rcb, RCB_ELEMENT_RPT_ENA | RCB_ELEMENT_TRG_OPS | RCB_ELEMENT_INTG_PD |RCB_ELEMENT_DATSET, true);

if (error != IED_ERROR_OK)
    printf("report activation failed (code: %i)\n", error);

/* trigger GI report */
/*使能总召唤*/
ClientReportControlBlock_setGI(rcb, true);
/*使在报告控制块里添加总召唤的参数*/
IedConnection_setRCBValues(con, &error, rcb, RCB_ELEMENT_GI, true);

while (state == running)
{
    ;
}

/*关闭报告控制块*/
ClientReportControlBlock_setRptEna(rcb, false);

2. 收到报告时的回调函数

void reportCallbackFunction(void* parameter, ClientReport report)
{
    /*获取报告中的数据*/
    MmsValue* dataSetValues = ClientReport_getDataSetValues(report);
    /*获得数据集列表*/
    LinkedList * list = (LinedList *) parameter;

    int i;
    /*遍历数据集*/
    while (LinkedList_getNext(list) != NULL)
    {
         /*获取下一个节点，可能是为了便于便利，获取到的LinkedList的实际值时从第二个节点开始的*/
        list = LinkedList_getNext(list);
        /*获取上报原因*/
        ReasonForInclusion reason = ClientReport_getReasonForInclusion(report, i);
        /*这里如果reason是REASON_NOT_INCLUDED，是不能获取数据值的*/
        /*例如像数据变化时，可能只上报了1个数据，但是dataSetValues中会有所有数据的索引，只不过其他数据的reason将会是REASON_NOT_INCLUDED*/
        if (reason != REASON_NOT_INCLUDED) {
        /*这里MmsValue_getBoolean只是假设返回的都是boolean类型，实际应用中要根据实际数据类型调用不同的函数*/
            printf("  %s : %i (included for reason %i)\n", list->data, i, MmsValue_getBoolean(MmsValue_getElement(dataSetValues, i)), reason);
        }
    }
}