Service indication hooks with default action implementation

After verifying the validity of the request, the API tries to locate the specified object. If the object exists and if the Time Stamp parameter matches the most recent time for the event being acknowledged, then the following will happen: the bit in the Acked_Transitions property of the object which corresponds to the value of the Event State Acknowledged parameter is set to 1, a result(+) primitive is issued, and an event notification with a Notify Type parameter equal to ACK_NOTIFICATION is issued. If an object is not found, a result(-) primitive is issued. An acknowledgment notification uses the same service type (acknowledged or unacknowledged) directed to the same recipients where the original acknowledged or unacknowledged event notification was sent. The Time Stamp conveyed in the acknowledgment notification is derived from the time when the acknowledgment notification is generated, not from the Time Stamp of the original event notification.

After verifying the validity of the request, the API searches all event-triggering objects that have a Event_State property not equal to NORMAL and a Notify_Type property with a value of ALARM. A positive response is constructed which contains the Alarm Summaries for objects found in this search. If no objects are found which fulfill these criteria, then a list of length 0 is returned.

After verifying the validity of the request, the API searches for all event-triggering objects which fulfill the search criteria specified in the request primitive. The search criteria are the logical links of all of the explicitly set filters which were omitted in the request primitive. A positive response containing the Enrollment Summaries for objects found in this search is constructed. If no objects are found which fulfill these criteria, then a list of length 0 is returned.

If neither Lifetime nor Issue Confirmed Notifications exist, then the request is considered as a cancellation. Any COV context, which already exists for the same BACnet address and is contained in the PDU which has the SubscribeCOV request and has the same Subscriber Process Identifier and Monitored Object Identifier, are disabled and a SimpleAck is returned. Created cancellations, for which matching COV context cannot be found, is performed successfully as if a context had existed and returns a SimpleAck. If the Lifetime parameter does not exist, but the Issue Confirmed Notifications does exist parameter, then a value of zero (indefinite lifetime) is applied for lifetime. If the Issue Confirmed Notifications parameter exists, but the object to be monitored does not support COV reporting, then an error is issued. If the object to be monitored supports COV reporting, then a check is performed to locate an existing COV context for the same BACnet address which is contained in the PDU that contains the SubscribeCOV request and has the same Subscriber Process Identifier and Monitored Object Identifier. If an existing COV context is found, then the request is handled as if the subscription is created again. If a COV context cannot be found which corresponds to the request, then a new COV context is created which contains the BACnet address from the PDU that carries the SubscribeCOV request and the same Subscriber Process Identifier and Monitored Object Identifier. If a context cannot be created, then an error is returned. If a new context is created, or a new subscription is received, then the COV context is initialized and given a lifetime according to the Lifetime parameter if it exists, or 0 if the Lifetime parameter does not exist. The subscription is automatically canceled after many seconds have elapsed without receiving a resubscription. A lifetime of 0 indicates that the subscription is indefinite and an automatic cancellation will not occur. In either case, a SimpleAck is returned. A ConfirmedCOVNotification or UnconfirmedCOVNotification is created as soon as possible after the successful completion of a subscription or re-subscription request, as specified in the Issue Confirmed Notifications parameter.

After verifying the validity of the request, the API tries to modify the object which is identified in the Object Identifier parameter. If the identified object exists and has the property specified in the Property Identifier parameter, then an attempt is made to add all of the elements specified in the List of Elements parameter to the specified property. If this attempt is successful, then a SimpleAck primitive is issued. If one or more of the elements already exists in the list, then it is ignored and not added to the list. Ignoring an element which already exists does not cause the service to fail. If the specified object does not exist, or the specified property does not exist, or the specified property is not a list, then the service fails and an error response primitive is issued. If one or more elements cannot be added to the list and they are not already in the list, then an error response primitive is issued and no elements are added to the list. The effect of this service is to add to the list all of the specified elements which do not already exist or to not add any elements to the list at all.

After verifying the validity of the request, the API tries to modify the object which is identified in the Object Identifier parameter. If the identified object exists and has the property specified in the Property Identifier parameter, then an attempt is made to remove all of the elements specified in the List of Elements parameter from the specified property. If one or more of the elements does not exist or cannot be removed because of insufficient permissions or other problems, then none of the elements are removed and an error response primitive is issued.

After verifying the validity of the request, the API tries to access the specified property of the specified object. If the access is successful, then a ComplexAck primitive is generated which returns the accessed value. If the access fails, then an error primitive is generated, which provides the reason for the failure. When the object-type in the Object Identifier parameter contains the value Device Object and the instance in the Object Identifier parameter contains the value 4194303, then the API handles the Object Identifier as if it correctly matched the local device object. This allows the device instance of a device which does not generate I-Am messages to be determined.

After verifying the validity of the request, the API tries to access the specified property of the specified object. It constructs a List of Read Access Results in the order as specified in the request. If the List of Property References part of the List of Read Access Specifications parameter contains the property identifiers ALL, REQUIRED, or OPTIONAL, then the List of Read Access Results is constructed as if each property being returned were explicitly referenced. There is no requirement that the request is performed "automatically". Nonetheless, the API makes sure that all read operations are completed in the shortest possible time, subject only to higher priority processes. The request is processed until an attempt is made to access all specified properties. If none of the specified objects are found or if none of the specified properties of the specified objects can be accessed, then either an error primitive or a ComplexAck primitive that returns error codes for all properties is issued. If any of the specified properties of the specified objects can be accessed, then a ComplexAck primitive is issued, which returns all accessed values and error codes for all properties that could not be accessed. When the object-type in the Object Identifier part of the Read Access Specification parameter contains the value Device Object and the instance in the Object Identifier parameter contains the value 4194303, then the API handles the Object Identifier as if it correctly matched the local device object. This allows the device instance of a device which does not generate I-Am messages to be determined.

For BACnet server user applications, which cannot use the internal database and therefore have to implement support for the ReadPropertyMultiple service, they only have to implement the ReadProperty service hook because ReadPropertyMultiple requests are split into single ReadProperty requests internally and completions are collected to create the response.

After verifying the validity of the request, the API tries to modify the specified property of the specified object by using the value provided in the Property Value parameter. If this modification attempt is successful, then a SimpleAck primitive is issued. If the modification attempt fails, then an error primitive is generated, which provides the reason for the failure.

For each Write Access Specification contained in the List of Write Access Specifications, the value of each specified property is replaced by the property value provided in the Write Access Specification, and a SimpleAck primitive is issued, indicating that the service request has been performed in its entirety. The provided properties are processed in the order which is specified in the List of Write Access Specifications. If during the processing a property is encountered which cannot be modified, then the PI issues an error response primitive indicating the reason for the failure. The result of this service is either that all of the specified properties or only the properties up to, but not including, the property specified in the First Failed Write Attempt parameter were successfully modified. A BACnet-Reject-PDU is issued only if no write operations have been executed successfully. It indicates that the service request was rejected in its entirety. If one of the write operations contained in the List of Write Access Specifications could not be executed successfully, then an error response indicating the reason for the failure is issued as described above.

First, the API verifies the validity of the Object Identifier, Property Identifier, and Property Array Index parameters, and returns an error response with the appropriate error class and error code if the object or property is unknown, if the referenced data is not a list or array, or if it currently cannot be accessed for another reason. If the Range parameter does not exist, then the API reads all of the available items in the list or array and tries to return them. If the Range parameter exists and specifies the By Position parameters, then the API reads all of the specified items and tries to return them. The specified items include the item at the index position defined by Reference Index plus those up to Count - 1 items following if Count is positive, or up to -1 - Count items preceding if Count is negative. The first element of a list is associated with index 1. If the Range parameter exists and specifies the By Time parameter or the By Sequence Number parameters, then the API rejects the request by returning an error response with the appropriate error class and error code. The returned response transmits the number of items read and returned by means of the Item Count parameter. The current items are returned in the Item Data parameter. If the returned response includes the first position index, then the FIRST_ITEM flag is set to TRUE in the Result Flags parameter; otherwise, it is set to FALSE. If the returned response includes the last position index, then the LAST_ITEM flag is set to TRUE in Result Flags; otherwise, it is set to FALSE. If no items in the list match the Range parameter criteria, then a ComplexAck is returned with an Item Count of 0 and no First Sequence Number parameter.

The default implementation of this service does NOT support access to the log-buffer property of the trend- and event-logging objects. If a user application has to support logging objects, then the storage and the access to those data has to be implemented by the user application.

If neither Lifetime nor Issue Confirmed Notifications exist, then the request is considered as a cancellation. Any COV context which already exists for the same BACnet address and is contained in the PDU which has the SubscribeCOVProperty request and has the same Subscriber Process Identifier, Monitored Object Identifier and Monitored Property Identifier, is disabled, and a SimpleAck is returned. Cancellations, which are issued for which no matching COV context can be found, are handled successfully as if a context had existed. They return SimpleAck. If a COV context is found, then it is removed from the Active_COV_Subscriptions device object. If the Issue Confirmed Notifications parameter exists, but the property to be monitored does not support COV reporting, then an error is issued. If the property to be monitored supports COV reporting, then a check is performed to locate an existing COV context for the same BACnet address which is contained in the PDU that contains the SubscribeCOVProperty request and has the same Subscriber Process Identifier, Monitored Object Identifier, and Monitored Property Identifier. If an existing COV context is found, then the request is interpreted as a resubscription and handled successfully as if a resubscription had been created. If a COV context that matches the request cannot be found, then a new COV context is created. It contains the BACnet address from the PDU which sends the SubscribeCOVProperty request and has the same Subscriber Process Identifier, Monitored Object Identifier, and Monitored Property Identifier. The new context is included in the Active_COV_Subscriptions property of the device object. If a context cannot be created, then an error is returned. If a new context is created, or a resubscription is received, then the COV context is initialized and defined with a lifetime as specified in the Lifetime parameter. The subscription is automatically canceled if a resubscription has not been received after many seconds. A SimpleAck is returned and a ConfirmedCOVNotification or UnconfirmedCOVNotification is created as soon as possible after the successful completion of a subscription or resubscription request, as specified in the Issue Confirmed Notifications parameter.

After verifying the validity of the request, the API searches for all event-triggering objects which meet the following conditions, beginning with the object (in ascending internal ordering of object instances) after the object specified by the Last Received Object Identifier parameter, if present have an Event_State property whose value is not equal to NORMAL, or have an Acked_Transitions property that has at least one of the following bits (TO-OFFNORMAL, TO-FAULT, TO-NORMAL) set to FALSE. A positive response is constructed, which contains the event summaries for objects found in this search. If no objects are found which fulfill these criteria, then a list of length 0 is returned. As many are returned as can be returned within the APDU. If more objects exist which fulfill the criteria but cannot be returned in the APDU, then the More Events parameter is set to TRUE; otherwise, it is set to FALSE.

After verifying the validity of the request, the API adds the received information to the Address_Binding device object property. This is used to resolve device instance numbers into BACnet MAC addresses which are needed for communication with that device.

After verifying the validity of the request, the API adds the received information to an internal sorted list. This list is used to resolve object names into object identifiers which are needed for accessing those objects.

The API will transmit the unacknowledged Who-Has request, normally using a broadcast address. If the Device Instance Range Low Limit and Device Instance Range High Limit parameters exist, then the API, whose device Object_Identifier instance number falls in the range Device Instance Range Low Limit >= Object_Identifier Instance Number <= Device Instance Range High Limit, is qualified to respond. If the Object Name parameter exists, then the API, which contains an object with an Object_Name property value that matches the Object Name parameter, responds with an I-Have service request. If the Object Identifier parameter exists, then the API, which contains an object with an Object_Identifier property value that matches the Object Identifier parameter, responds with an I-Have service request.

The API transmits the unacknowledged Who-Is request, normally using a broadcast address. If the Device Instance Range Low Limit and Device Instance Range High Limit parameters are missing, then the API returns their device Object_Identifiers in individual responses by means of the I-Am service. If the Device Instance Range Low Limit and Device Instance Range High Limit parameters exist, then the API, whose device Object_Identifier instance number falls within the range Device Instance Range Low Limit >= Device Object_Identifier Instance Number <= Device Instance Range High Limit, will return their device Object_Identifier by means of the I-Am service.

First, the API verifies the validity of the Object Identifier. It returns a result(-) error with the corresponding error class and error code if the object is unknown. This service hook supports only files accessed via STREAM. After that, the validity of the local file access on the local hard drive is checked and a result(-) response with the appropriate error class and error code is returned if the file start position is invalid or if the file is not accessible for any reason. If the validity check is successful, then the specified number Request Record Count of octets is read from the local file. If the actual number of read octets is less than the specified one, then the Returned Record Count of the returned result(+) indicates the number of read octets. If the end of the file is reached, then the End Of File parameter of the returned result(+) is set to TRUE.

This service hook is implemented using the SysFile interface of CODESYS and supports STREAM access only. As a result, the user application may want to change particularly this service hook for the file access.

First, the API verifies the validity of the Object Identifier. It returns a result(-) error with the corresponding error class and error code if the object is unknown. This service hook supports only files accessed via STREAM. After that, the validity of the local file access on the local hard drive is checked and a result(-) response with the appropriate error class and error code is returned if the file start position is invalid or if the file is not accessible for any reason. If the File Start Position parameter of the service request exceeds the local file size, then the file is extended for writing the incoming octets. If the File Start Position parameter has the value -1, then the local file is appended with the incoming octets. If writing to the local file fails, then a corresponding result(-) response is issued. If writing to the local file is successful, then result(+) is issued, which contains the corresponding File Start Position.

This service hook is implemented using the SysFile interface of CODESYS and supports STREAM access only. As a result, the user application may want to change particularly this service hook for the file access.

First, the API will verify the validity of the request by checking whether or not the Object Specifier of the request specifies a creatable object type (according to the internal rule BACnet.IsBACnetObjectAMEVCreatable). It returns a corresponding error result(-) if this is not the case. If specified by the Object Specifier, the validity of the object instance number is checked and a corresponding error result(-) is returned in case the instance number does not exist anymore. If a List of Initial Values is not specified, then properties of the created object are created by using default values as it is usual for properties which are not specified in a given List of Initial Values. If the creation of the object fails, then a corresponding error result(-) is issued, while the First Failed Element Number of the response is set to 0. If the creation was successful, a result(+) response is issued, which contains the object identifier of the created object.

This current implementation of this service hook should be seen as more of a comprehensive suggestion for its implementation. Because it is a purely local matter of the user application how this service request is handled, it is very likely that the user application will supply its own service hook for another handling of the request.

First, the API verifies the validity of the Object Identifier and returns a result(-) error response with the corresponding error class and error code if the object is unknown. If the specified object can be deleted, then a result(+) response is issued. If the deletion of the objects fails (example: the object cannot be deleted dynamically according to the internal rule BACnet.IsBACnetObjectAMEVCreatable), or for any other reason, then a result(-) is issued.

This current implementation of this service hook should be seen as more of a comprehensive suggestion for its implementation. Because it is a purely local matter of the user application how this service request is handled, it is very likely that the user application will supply its own service hook for another handling of the request. For more information, see: Implementation Requirements when Using the Current BACnet API/Stack