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_VARBeachten 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_IFDie 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