Skip to main content

Service Hook: CreateObject, Implementierungsbeispiel

Das folgende Beispiel zeigt, wie ein CreateObject Service Hook implementiert werden kann, wenn der/die BACnet Stack/API verwendet wird.

Zuerst muss der entsprechende Hook irgendwo in Ihrem Programmcode eingetragen werden. Dies erfolgt durch Eintragen eines Funktionsbausteins CallbackFB, der die Schnittstelle IBACnetEventConsumer implementiert, mit der Funktion RegisterHook des BACnetServer-FBs. Also Eintragen des Funktionsbausteins, der für das lokale BACnetServer-Gerät im CODESYS-Gerätebaum eingefügt ist:

BACnetServer.RegisterHook(CmpBACnet.IEC_BACNET_CB_TYPE.CB_CREATE_OBJECT, CallbackFB);

Wenn dies erfolgt ist, wird diese Funktion dieses FBs BACnetEventCallback (definiert durch die Schnittstelle IBACnetEventConsumer) aufgerufen, sobald eine CreateObject-Service-Anfrage vom BACnetServer (in anderen Worten: BACnet-Gerät) aufgefangen wird. Das folgende Beispiel zeigt eine Implementierung der BACnetEventCallback-Funktion des CallbackFB. Er hat folgende Deklaration:

METHOD BACnetEventCallback : BOOL
VAR_INPUT
    (*If only one event is possibly called, the following Ids can be ignored. If there are
         more at least the EventId should be checked, to get the right type of pParameter.   ID of the occured Event. Contains the class and the event.*)
    EventId : DWORD;
    (*Id of the parameter structure (see pParameter)*)
    usParamId       : WORD;
    (*Version of the parameter structure (see pParameter)*)
    usVersion       : WORD;
    (*Pointer to the event specific parameter, that is specified by Id (see GVL EVENTID in
         CmpBACnet)*)
    pParameter      : POINTER TO BYTE;
END_VAR
VAR
    pCreateObj : POINTER TO CmpBACnet.EVT_BACNET_CREATEOBJECT;

    destInstNumber : CmpBACnet.IEC_BACNET_DWORD;

    objSpec : CmpBACnet.IEC_BACNET_OBJECT_SPECIFIER;
    objID : CmpBACnet.IEC_BACNET_OBJECT_ID;

    i : UDINT;
    bacObj : BACnetObjectBase;
    runObjID : CmpBACnet.IEC_BACNET_OBJECT_ID;
    objCount : UDINT := 0;

    strBuffer : STRING;
    errCode : CmpBACnet.IEC_BACNET_ERROR_CODE := 0;
    bacResult : CmpBACnet.IEC_BACNET_STATUS;

END_VAR

Beachten Sie, dass die pCreateObj-Variable, die die Basisinformation der CreateObject-Anfrage trägt. Der Code der BACnetEventCallback-Funktion des CallbackFB könnte wie folgt implementiert werden:

    BACnetEventCallback := FALSE;

//Check if the issued service event is the one we are interested in
//meaning the create object event
IF EventId = CmpBACnet.EVT_CreateObject AND
   usParamId = CmpBACnet.EVTPARAMID_CmpBACnet_CreateObject AND
   usVersion = CmpBACnet.EVTVERSION_CmpBACnet_CreateObject THEN

    //Get the service information using the proper
    //event structure CmpBACnet.EVT_BACNET_CREATEOBJECT
    pCreateObj := pParameter;

    //The pCBStatus property of the event structure allows to define
    //the result of this service hook. Choosing the default action
    //will advice the API to use its default implementations if available
    //(see also documentation of CB_STATUS_DEFAULT)
    pCreateObj^.pCBStatus^ := CmpBACnet.IEC_BACNET_CB_STATUS.CB_STATUS_DEFAULT;
    //Get the device instance number for the service request and check if it is
    //our device that the request is for (only important for the case of multiple
      //devices in one PLC)
      bacResult := CmpBACnet.BACnetDeviceAddressToInstNumber(pCreateObj^.destinationAddress,
                                                             ADR(destInstNumber));
                       IF bacResult = CmpBACnet.IEC_BACNET_STATUS.BACNET_STATUS_OK AND destInstNumber = m_Device.DeviceInstNumber THEN
                            //Get the object specifier defining what to create
                            objSpec := pCreateObj^.pServiceInfo^.objectSpecifier;
                            //Check if the object type specified is creatable
                            IF IsBACnetObjectAMEVCreatable(objSpec.objectSpec.typ) THEN
                            //If no object ID is given find a free one
                                 IF objSpec.tag = CmpBACnet.IEC_BACNET_CREATE_OBJECT_TYPE.CREATE_OBJECT_TYPE THEN
                                    objID.typ := objSpec.objectSpec.typ;
                                    objID.instNumber := 1;
                                    objCount := GetObjectCount();
                                     i := 1;
                                  WHILE i <= objCount DO
                                     GetObject(i, bacObj);
                                     runObjID := bacObj.ObjectID;
                                     IF runObjID.typ = objID.typ AND
                                        runObjID.instNumber = objID.instNumber THEN
                                      objID.instNumber := objID.instNumber + 1;
                                      i := 1;
                                     END_IF
                                     i := i + 1;
                                  END_WHILE
                                  BACnetEventCallback := TRUE;
                                  //If the object ID is given check if it is a valid/free object ID
                                ELSIF objSpec.tag =
                                      CmpBACnet.IEC_BACNET_CREATE_OBJECT_TYPE.CREATE_OBJECT_ID THEN
                                     objID := objSpec.objectSpec.objectID;
                                     objCount := GetObjectCount();
                                     i := 1;
                                     BACnetEventCallback := TRUE;
                                  WHILE i <=  objCount DO
                                    GetObject(i, bacObj);
                                    runObjID := bacObj.ObjectID;
                                    IF runObjID.typ = objID.typ AND
                                      runObjID.instNumber = objID.instNumber THEN
                                    errCode := ERR_CODE_OBJ_ID_ALREADY_EXISTS;
                                    BACnetEventCallback := FALSE;
                                    EXIT;
                                    END_IF
                                  i := i + 1;
                                   END_WHILE
                            ELSE
                                //No object specification given which can be interpretated, so
                                //issue a standard error
                                BACnetEventCallback := FALSE;
                            END_IF
                      ELSE
                          //If the object type is not supported to be created issue the
                         //appropriate error
                         errCode := ERR_CODE_DYN_CREATION_NOT_SUPP;
                         BACnetEventCallback := FALSE;
                       END_IF

                      //If everything is all right till now (BACnetEventCallback is TRUE) try to
                      //create the object
                      IF BACnetEventCallback THEN
                         IF pCreateObj^.pServiceInfo^.fValuesPresent > 0 THEN
                         //If property values are given by the service request use them
                         bacResult := CmpBACnet.BACnetConstructObject(destInstNumber,
                                      ADR(objID), pCreateObj^.pServiceInfo^.pValues,
                                      pCreateObj^.pServiceInfo^.nValuesCount,
                                      m_SupportUnsolicitedCOV, 1, m_HideToOutside);
                           ELSE
                                 //If no property values are given by the service request just
                                 //create the object using the default implementation
                                 bacResult := ConstructDefaultObject(objID.typ, objID.instNumber,
                                STRING_TO_WSTRING(CONCAT('CreatedObject', DWORD_TO_STRING(objID.instNumber))),
                                                                    bacObj, strBuffer);
                           END_IF
                        END_IF

                         //Check if everything went well
                         IF BACnetEventCallback AND bacResult = BACNET_STATUS_OK THEN
                            //If everything succeeded issue an result(+) response containing the
                            //object ID
                            CmpBACnet.BACnetCreateObjectResponseCbCompletion(pCreateObj^.phTransaction,
                            ADR(objID));
                          //We treated the service request, so no default API actions are
                         //necessary anymore
                            pCreateObj^.pCBStatus^ := CmpBACnet.IEC_BACNET_CB_STATUS.CB_STATUS_OK;
                         ELSE
                             //If something went wrong issue an error
                             BACnetEventCallback := FALSE;
                             //If no explicit error code was given till now, issue an internal error
                             IF errCode = 0 THEN
                                errCode := ERR_CODE_INTERNAL_ERROR;
                             END_IF
                             //Issue the result(-) response with the appropriate error code
                             CmpBACnet.BACnetCreateObjectErrorCbCompletion(pCreateObj^.phTransaction,
                             ERR_CLASS_OBJECT, errCode, 0);
                             //We treated the service request, so no default API actions are
                             //necessary anymore
                             pCreateObj^.pCBStatus^ := CmpBACnet.IEC_BACNET_CB_STATUS.CB_STATUS_OK;
                          END_IF
                       END_IF
END_IF

Die wichtigste Funkitionalität in diesem Code-Beispiel ist, die Service-Anfrage-Information zu erhalten, indem ein Casting von pCreateObj (EVT_BACNET_CREATEOBJECT) auf pParameter durchgeführt wird, um dann auf die Information in pParameter zugreifen zu können. pCreateObj ist eine typische Hook-Anfrage-Struktur (gefunden und deklariert in der Bibliothek CmpBACnet), wobei meistens eine Variable pCBStatus enthalten ist, die der Rückgabewert an die API ist. Dieser Rückgabewert entscheidet, ob die API die Service-Anfrage weiter bearbeitet (Default) oder nicht (OK). Der Rest des Codes prüft hauptsächlich die Propertys der Service-Anfrage und versucht dann das Objekt zu erzeugen, wobei auftretende Fehler in der Variablen errCode gespeichert werden. Schließlich werden result(+)- oder result(-)-Antworten erzeugt, unter Verwendung der Funktionen CmpBACnet.BACnetCreateObjectResponseCbCompletion oder CmpBACnet.BACnetCreateObjectErrorCbCompletion.

Dies ist ein typisches Beispiel eines implementierten Service Hooks, in dem die Event-Mechanismen des BACnet Stack/API genutzt werden: Es git ein Event/Callback, das Sie eintragen können, um immer dann einen Aufruf zu erhalten wenn eine Service-Anfrage empfangen wurde. Die Implementierung des Service Hooks muss dann den Spezifikationen des BACnet-Standards folgen, um einen konformen Service bereitzustellen.

Für weitere Informationen siehe auch: Implementierungsanforderungen bei Verwendung des derzeitigen BACnet API/Stacks