Access Control

SiPass® integrated

Management Station-API (DCOM)

Programmer’s Reference Manual

MP2.85

A-100026-1 Smart Infrastructure

05.2021
Copyright
Technical specifications and availability subject to change without notice.
© Copyright Siemens Switzerland Ltd.
We reserve all rights in this document and in the subject thereof. By acceptance of
the document the recipient acknowledges these rights and undertakes not to
publish the document nor the subject thereof in full or in part, nor to make them
available to any third party without our prior express written authorization, nor to
use it for any purpose other than for which it was delivered to him.
Edition: 05.2021
Document ID: A-100026-1
Contents
1 About this document .............................................................................. 5

2 Introduction ............................................................................................. 6

3 Updates from Previous Release ............................................................ 7

3.1 MP2.80 to MP2.85 .................................................................................... 7
3.2 MP2.76 SP2 to MP2.80 ............................................................................ 8
3.3 MP2.76 SP1 to MP2.76 SP2..................................................................... 8
3.4 MP2.76 to MP2.76 SP1 ............................................................................ 8
3.5 MP2.75 to MP2.76 .................................................................................... 9
3.6 MP2.70SP1 to MP2.75 ........................................................................... 10
3.7 MP2.70 to MP2.70 SP1 .......................................................................... 10

4 The Management Station API .............................................................. 11

4.1 Object Model Overview ........................................................................... 12
4.2 Requirements .......................................................................................... 13

5 Using the API ......................................................................................... 14

5.1 Accessing SiPass integrated objects ...................................................... 14
5.1.1 Development Using Visual Studio 2015 or later ..................................... 15
5.2 Enumerator Explanation ......................................................................... 16

6 Object Reference .................................................................................. 18

6.1 COMClient Object ................................................................................... 18
6.2 Generic Object ........................................................................................ 22
6.2.1 Example .................................................................................................. 22
6.3 Server Info Object ................................................................................... 23
6.3.1 Example .................................................................................................. 23
6.4 Bus Object............................................................................................... 24
6.4.1 Example .................................................................................................. 24
6.5 Unit Object .............................................................................................. 25
6.5.1 Example .................................................................................................. 25
6.6 FLN Object .............................................................................................. 26
6.6.1 Example .................................................................................................. 26
6.7 Device Object .......................................................................................... 27
6.7.1 Example .................................................................................................. 27
6.8 Hub Object .............................................................................................. 28
6.9 Door Set Object ...................................................................................... 29
6.9.1 Example .................................................................................................. 29
6.10 Point Object............................................................................................. 30
6.10.1 Example .................................................................................................. 30
6.11 Area Object ............................................................................................. 31
6.11.1 Example .................................................................................................. 31
6.12 Flag Object .............................................................................................. 32
6.12.1 Example .................................................................................................. 32
6.13 Counter Object ........................................................................................ 33
6.13.1 Example .................................................................................................. 33
6.14 Timer Object............................................................................................ 34
6.14.1 Example .................................................................................................. 34
6.15 Anti-Passback Cluster ............................................................................. 35
6.15.1 Example .................................................................................................. 35
6.16 Anti-Passback Area ................................................................................ 36
6.16.1 Example .................................................................................................. 36
6.17 Bank Object............................................................................................. 37
6.17.1 Example .................................................................................................. 37

Smart Infrastructure A-100026-1

6.18 External System Object ........................................................................... 38
6.19 External System Point Object ................................................................. 38
6.20 SubscriptionEvent Object ........................................................................ 39
6.20.1 Example .................................................................................................. 39
6.21 Alarm Class Object ................................................................................. 41
6.21.1 Example .................................................................................................. 41
6.22 Generic Event Object .............................................................................. 42
6.22.1 Example .................................................................................................. 42
6.23 Database Event Object ........................................................................... 43
6.23.1 Example .................................................................................................. 43
6.24 State Object............................................................................................. 44
6.24.1 Example .................................................................................................. 44
6.24.2 State limitations for External System Points ........................................... 45
6.25 APB Area State Object ............................................................................ 46
6.25.1 Example .................................................................................................. 46
6.26 Access Event Object ............................................................................... 48
6.26.1 Example .................................................................................................. 48
6.27 Alarm Object............................................................................................ 49
6.27.1 Example .................................................................................................. 49
6.28 Alarm Action Object ................................................................................ 50
6.28.1 Example .................................................................................................. 50
6.29 Manual Command Object ....................................................................... 51
6.29.1 Example .................................................................................................. 51
6.30 OSS-SO Sites Object .............................................................................. 52
6.31 OSS-SO Site Object ................................................................................ 53
6.32 OSS-SO Reader Object .......................................................................... 54

7 Code Samples........................................................................................55
7.1 SiPass integrated Management Station Test Program ........................... 55
7.2 Source Files ............................................................................................ 55

8 Appendix A: Error Codes .....................................................................56

9 Appendix B: Enumeration Definitions ................................................58

1 About this document
Reference Manual
The SiPass® integrated Management Station API Reference Manual has been
prepared to provide you with information concerning the configuration and
operation of the SiPass Management Station option.
It has been produced for new and experienced users of Siemens Building
Technologies access control products and systems. This guide should be used in
conjunction with the SiPass Installation and User’s manuals.

Disclaimer
Although reasonable care was taken in producing this manual, no responsibility is
accepted by Siemens or its agents or employees for the accuracy or safety of the
material contained herein. None of the equipment described in this guide is
suitable for use in an application where life or health depends on its correct
operation. Siemens reserves the right to vary the specifications, standards and
method of operation of any or all of the equipment described herein at any time
without notice to any party.
No liability can be assumed for direct or consequential losses and third-party
damages arising from the purchase of this product. In all cases, liability is limited to
the purchase price of the product.
The information contained herein was up to date at the time of publication. We
reserve the right to make subsequent changes to technical or organizational
details. Siemens assumes no liability for problems resulting from the use of this
manual.
The information contained in this document may be changed without prior notice.
Siemens reserves the right to publicize any such changes by issuing updated
versions or new editions.
Siemens Fire Safety & Security Products confers upon the purchaser the right to
use the software.
It is not permitted to reproduce this manual in whole or in part or translate it into
another language without our written consent.

Contacting us
If you have questions or suggestions regarding the product or this documentation,
please contact your local SiPass integrated representative.

Smart Infrastructure A-100026-1

2 Introduction
This Reference Manual explains how to access and maintain SiPass® integrated
device information from a software application external to SiPass, such as the
Management Station Test application.
This guide has been produced as a reference for any personnel developing or
extending software applications that require access to SiPass integrated devices.
This guide should be used in conjunction with the SiPass integrated Installation
and User Guides.

Information in this chapter includes:

– Management Station API Overview

– Object Model Overview

 Updates from Previous Release

3 Updates from Previous Release

The following changes have been made to MS-API since the previous version
of SiPass integrated was released.
The content of this document may be modified for a release depending on the
functionality or any change in behaviour in SiPass integrated. While working on
a specific MS-API release, it is recommended to consult the MS-API Guide for
that specific release to ensure that you get the appropriate help.

3.1 MP2.80 to MP2.85

• The list of files given in section “Development Using Visual Studio 2015 or later”
has been updated to include two additional files:
o Si.ClientServiceFactory.dll
o SiPass.ClientServiceFactory.dll

• A new MS-API EPointOpMode enum value has been added to support the new
Input Point Operation Mode - Door Frame Held Only.
The new EPointOpMode enum is eInpDCHeldOnlyMode = 122
Note: The RESTful MS-API utilizes the above for which, the RESTful MS-API
Object Model content has been updated.

• Enhancement to support the OSS-SO functionality:

New EObjType enums:
o eOSSSOSites = 32
o eOSSSOSite = 33
o eOSSSOReader = 34
New interfaces:
o IOSSSOSites
o IOSSSOSite
o IOSSSOReader
Note: Section 6 and Appendix B in this document have also been updated for
the above.

• A new error code has been added to Appendix A: Error Codes table for a
message shown in SiPass integrated Configuration and Operation Clients when
Remote SQL service is stopped:
o ADV_E_SQL_STATUS_OFFLINE

7
Smart Infrastructure A-100026-1
3.2 MP2.76 SP2 to MP2.80
• To incorporate MS-API login to WCF service, new sample config files are
available, along with updated instructions in section 5.
• Enhancement to support MFI controller
o New ESubType “eMFI = 4024”
o New EDoorSetType enumerations:
▪ eMFI_2Single_0Dual = 36, // MFI 2 Single Reader Doors
▪ eMFI_4Single_0Dual = 37, // MFI 4 Single Reader Doors
▪ eMFI_0Single_2Dual = 38, // MFI 2 Dual Reader Doors
▪ eMFI_0Single_4Dual = 39, // MFI 4 Dual Reader Doors
▪ eMFI_TS_2Single_0Dual = 40, // MFI 2 Turnstiles, Single DC
▪ eMFI_TS_0Single_2Dual = 41, // MFI 2 Turnstiles, Dual DC
▪ eMFI_IO_Only = 42, // MFI I/O Only (No doors)
• Two new device object states (enums) have been added to EObjState:
eDeviceOnlineStandardComms, eDeviceOnlineLegacyComms

3.3 MP2.76 SP1 to MP2.76 SP2

• For EDoorSetType 'eAPERIO_BASIC_1Single_0Dual', a frame input is now
included in the result of the doorset query.

3.4 MP2.76 to MP2.76 SP1

• Enhancement to support Multiple Aperio Hubs:
o New ESubType "eAperioFLN"
o Component tree hierarchy is now "Unit --> Aperio FLN --> Aperio Hub -->
Aperio Lock". The old hierarchy was "Unit --> Aperio Hub --> Aperio Lock"
• Enhancement to support Wiegand protocol for DRIe:
o 4 new EDoorSetType enumerations for DRIe:
"eDRIe_0Single_1Dual_Wiegand", "eDRIe_2Single_0Dual_Wiegand",
"eDRIe_TS_2Single_0Dual_Wiegand",
"eDRIe_TS_0Single_1Dual_Wiegand"
 Updates from Previous Release
3.5 MP2.75 to MP2.76
• Enhancement to support Aperio ‘Hub’ entity
o New EObjType ‘eHub’
o New ESubType ‘eAperio_AH30’
o New interface ‘IHub’ (just extends from existing ‘IGenericObj’, no new
properties)
o Object state support for Hub – existing states ‘eCommsBack’ and
‘eCommsLost’ to be used
• Enhancement to support Aperio ‘Basic Lock’ device (a device with one input
(REX), one output (latch), one access point):
o New ESubType ‘eAperioBasicLock’, (appears under existing ‘eDevice’
EObjType)
o New EDoorSetType ‘eAPERIO_BASIC_1Single_0Dual’ – consists of one
input (REX), one output (latch), one access point
• Enhancement to support new Aperio device states
o 3 new enums added to EObjState: 'eDeviceBatteryOk', 'eDeviceBatteryLow',
'eDeviceBatteryFailed'
• Enhancement to support Salto External System:
o New EObjTypes: 'eExternalSystem', 'eExternalSystems'
o New ESubType 'eSalto'
o New interfaces 'IExternalSystems', 'IExternalSystem' (just extends from
existing ‘IGenericObj’, no new properties)
o New object state subtype ESubType 'eExternalSystemState'
o New object states in EObjState: 'eExternalSystemOnline',
'eExternalSystemOffline'
• Enhancement to support Salto External System Points:
o New EObjType 'eExternalSystemPoint'
o New ESubTypes 'eDoor', 'eLocker', 'eFreeAssignmentLocker'
o New interface 'IExternalSystemPoint' (just extends from existing
‘IGenericObj’, no new properties)
o New object state subtype ESubType 'eExternalSystemPointState'
o New object states in EObjState:
▪ eDoorValidCode,
▪ eDoorOpened,
▪ eDoorInEmergencyState,
▪ eDoorOpeningNotAllowed,
▪ eDoorInvalidPin,
▪ eDoorTamper,
▪ eDoorOnline,
▪ eDoorOffline,
▪ eDoorAntipassbackError,
▪ eDoorCardNotActivated,
▪ eDoorCardExpired,
▪ eDoorTimeScheduleViolation,
▪ eDoorLeftOpened,
▪ eDoorBatteryLow
• Addition of new EPointMode enum ‘eAccCardAndPinAccessIntrusion’, for
Reader Operation Mode “Card and Pin Access/Intrusion”.
9
Smart Infrastructure A-100026-1
3.6 MP2.70SP1 to MP2.75
• Enhancement to support ACC-AP feature:
o New Unit subtype "eACCUnit_AP"
o New FLN subtype "eAPFLN"
o New Device subtype "eDRIe"
o New doorset enumerations for DRIe: "eDRIe_0Single_1Dual",
"eDRIe_2Single_0Dual", "eDRIe_TS_2Single_0Dual",
"eDRIe_TS_0Single_1Dual"
Note: Even if customer code is not updated for MP2.75, the ACC-AP/DRIe
objects will still be viewable in Management Station, it's just the "subtype"
property for these objects can't be recognised by application.

3.7 MP2.70 to MP2.70 SP1

• Enhancement to see TKE bank and floors
o New EObjType "eBanks" (parent for eBank objects)
o New IBanks interface - same as IGenericObj
o New ESubTypes to distinguish Bank objects - "eBankGeneric" &
"eBankDestinationControl"

• Add requested missing Access Point States:

o eNoPinEntered // Card badged at Card+PIN reader but no PIN entered.
o eCapacityFullDenied // Access Denied because Area Capacity limit reached
o eAccessibilityCardPresented // Accessibility Valid Card Presented
o eWorkgroupCapacityFullDenied // Access Denied because Workgroup
Capacity limit reached in Area
o eNoEntry // Cardholder did not enter (delayed reporting mode)
o eProgrammableAuthAccessDenied // Access Denied - Programmable
Authorization

• Add requested missing Input Point States:

o eInputUnsealed // Input Unsealed
o eInputSealed // Input Sealed
o eInputIsolated // Input Isolated
o ePassbackDenied // Input passback denied

• Add requested missing Output Point States:

o eOutputSlowPulse // Slow Pulse
o eOutputFastPulse // Fast Pulse

• Add two new properties to IObjState

o PointDisabledState and CommsStatus
o New enum EPointDisabledState for PointDisabledState property above
o New enum ECommsStatus for CommsStatus property above
Note: This may be a breaking change if existing code works with "Access
Events", since "IAccessEvent" derives from "IObjState", and any change to
IObjState affects IAccessEvent. In that case, customer code recompilation
would be required for code built before MP2.70 SP1.
• New interface object IAPBAreaObjState, which derives from IObjState. Sent for
APB state events and includes more information than normal object state.
Requested in BTQ00280402
 The Management Station API

4 The Management Station API

The SiPass integrated automation object model allows SiPass data to be accessed
and maintained from any programming language that supports COM automation
under Microsoft Windows XP or later.
Examples given in this document are written in C#, but the Management Station
API can be called from any programming language that supports COM automation.
The management station API uses a COM library. It consists of a set of COM
objects that will represent different SiPass integrated objects (for example, client,
units, points, object state, audit trail, etc.). Objects will be uniquely identified by
their type and by their ID (if they have any).
The main object is the COMClient object. The management station must create an
instance of this Client object and logon to the SiPass integrated server before any
other objects are created.
All COM objects except the Manual Command and Alarm Action objects are
noncreatable (i.e., they cannot be instantiated) and can be obtained only from the
COMClient object.
The purpose of the COM objects is to provide information to the management
station about different SiPass integrated objects.

The described methods throughout this document will not change except under exceptional
circumstances, where clear notice will be provided. However, undocumented methods may be subject
to change without any prior notice

11
Smart Infrastructure A-100026-1
4.1 Object Model Overview

The Management Station objects include:

Object Description

COMClient Provides access to the SiPass integrated server as well as other

objects except the Manual Commands and Alarm Action objects..

Generic Provides generic object information.

Server Info Provides information about the SiPass integrated server.

Bus Provides information about the selected Bus.

Unit Provides information about ACC Units.

FLN Provides information about FLNs.

Device Provides information about Devices.

Door Set Provides information about the Door Set.

Point Provides point information about points in the system: includes input
points, output points and access points.

Alarm Class Defines the alarm classes and associated instructions.

Generic Event Contains the base properties that apply to all events and the
information that can be displayed in the audit trail.

Database Event In addition to the generic information it provides database specific

event information.

State Provides State specific event information.

Access Event In addition to the generic and state information it provides access
point specific event information.

Alarm Represents alarms delivered to the management station.

AlarmAction Allows the operator to action an alarm.

Manual Command Send Manual Commands to SiPass integrated. Commands can be

created without the COMClient object, but they are sent by the
COMClient’s “Process” method.

SubscriptionEvent In addition to the generic information it provides subscription based

event specific informations.
 The Management Station API
4.2 Requirements

It is assumed that the reader is familiar with C#, or a similar object-oriented

programming language and concepts.
The programming language you are using to call the Management Station API
must support the Common Object Model (COM) object automation.

13
Smart Infrastructure A-100026-1
Using the API
5 Using the API
This chapter and the next describe each object in detail and explain how to access
SiPass integrated data using the object model.
Note: If SiPass integrated has been installed with the high security option, the MS-
API Client can connect to the SiPass integrated server ONLY AS LOCAL client (on
Server site). See the SiPass integrated Installation Manual for more information.

5.1 Accessing SiPass integrated objects

In order to use the Management Station API, you will need access to several DLL
files which are part of any SiPass integrated client installation.
If the Management Station API (MS API) is:
• In the same runtime folder as SiPass integrated, the appropriate localized
strings will be displayed in the components tree view.
• In a different folder, English strings will be displayed in the component tree
view (default).
You can customize the strings sent from MS API to a language of your choice
before displaying on your MS API application.
 Using the API
5.1.1 Development Using Visual Studio 2015 or later

Visual Studio 2015 (or later versions) can be used with .NET 4.8
for development as follows:
1. Open the Add References dialog and select the COM tab.
If SiPass integrated client has previously been installed, you will find an entry
called “COMClientAPI 1.0 Type Library”. Add this to your Management Station
API project.
2. Right-click the project in Solution Explorer and select Add Existing Item.
3. Add all the following files, which should exist in your SiPass integrated
installation folder:
a. behaviors.config
b. bindings.config
c. clients.config
d. extensions.config
e. ClientsShared.config
f. Si.Common.dll
g. Si.WcfClientServiceFactory.dll
h. Si.WcfServices.Interfaces.dll
i. SiPass.ClientServices.Interfaces.dll
j. SiPass.Common.dll
k. SiPass.Exception.dll
l. SiPass.Interfaces.dll
m. SiPass.WcfCoreServices.dll
n. WsSharedTypes.dll
o. Common.dll
p. Common.Logging.Interop.dll
q. Common.Unmanaged.dll
r. log4net.dll
s. Si.ClientServiceFactory.dll
t. SiPass.ClientServiceFactory.dll

4. For each of the newly added DLLs and config files above, ensure that the
property Build Action is set to Content, and the property Copy to Output
Directory is set to Copy Always.
5. Ensure the project's Platform Type is set to x86, since we are referencing
32-bit COM components.
6. Modify your Management Station Application configuration file by
following the template of the ms_api_sample_app.exe.config file available in
the SiPass integrated installation directory.

15
Smart Infrastructure A-100026-1
Using the API
5.2 Enumerator Explanation
Here is an explanation of the some of the less obvious enumerators used. The full
listing is available in the COMClientAPI.idl file. The COMClientAPI.idl file is
included with the Management Station Sample
As a general guide the Enumerators are written to match SiPass integrated
terminology and concepts as closely as possible. For any specific modes, states or
commands that you do not understand please refer to the SiPass integrated
Reference Manual and Audit Trail Manual.
Appendix B contains a list and descriptions of all the possible combinations of the
EObjType and ESubType enumerations

Enumerator Description

EDoorSetType The 15 possible states that describe the Door Set types.
The first part is the reader interface used, eg DRI, SRI, CX8,
NT8
The second part refers to the number of single and dual readers
that the door set reflects. Single refers to one reader per door,
whereas dual refers to two readers per door.

EPointOpMode The first section contains “NoOpMode” and “OPModeNotSet”.

“NoOpMode” should not be encountered, it is used to catch
unknown modes. “OpModeNotSet” occurs when a point returns a
valid status, but it does not have any operational modes.
The second section refers to input modes. They correspond
exactly with the Operation Modes listed in SiPass integrated. To
view these open the Component screen, select a device and
look at the Input Tab.
The third section refers to the Output modes as listed in the
SiPass integrated Component Screen.
The last section is the Reader Operation Modes. They modes
correspond with the modes visible in the Component Screen of a
Reader Interface, via the Reader Tab.

ECommand For each command in MS-API, there is a matching command in

SiPass integrated. These can be viewed by double-clicking the
Manual Override option from the left navigation pane of SiPass
integrated Operation Client.
The Command groupings in the Enumerators are exactly the
same.

EObjState These states are grouped into the objects that they refer to. They
often match the audit trail messages generated when the states
are changed.

ECounterMode eCounterModeUnknown - Unknown mode, possible database

issue
eWrapAround - The counter value becomes 0 after incrementing
past the max value
eEndLimit - Incrementing past the max value has no effect on
the counter

ETimerMode eTimerModeUnknown - Unknown mode, possible database

issue
eOnDelayTimer - The timer is increasing if the trigger for it is
true, but loses its value when its trigger becomes false
eRetentiveOnDelayTimer - The timer is increasing if the trigger is
true, and retains its value when its trigger is false (but stops
increasing)
ePeriodicTimer - The timer begins increasing if the trigger is true,
and keeps resetting to 0 when the period is reached
 Using the API

EAPBAreaMode eAPBAreaUnknownMode - Unknown mode, possible database issue

eAPBAreaHardMode - Hard Anti-Passback
eAPBAreaSoftMode - Soft Anti-Passback
eAPBAreaFailSoftMode - Fail-Soft Anti-Passback
eAPBAreaTimedReEntryMode - Timed Re-Entry
eAPBAreaNoAPBMode - No Anti-Passback

ESubscriptionType eUnknownType - Unknown subscription event type

eCounterState - Counter event subscription
eTimerState - Timer event subscription
eAPBAreaState - APB area subscription

ESubscribedValueType eSubscribedAsUnknown - Unknown value type is returned by

subscription based events
eSubscribedAsLong - Long value type is returned by subscription based
events
eSubscribedAsEnum – Enum value type is returned by subscription
based events

17
Smart Infrastructure A-100026-1
Object Reference
6 Object Reference
This section lists a description of each available object and its properties and
methods. A syntax and usage example can be found in each of the descriptions.

6.1 COMClient Object

The COMClient object allows the operator to connect to the SiPass integrated
server and access all the other objects except the Manual commands. The Manual
commands can be constructed independently but they must be submitted to the
COMClient object for final action.
The interface for this object is: ICOMClient
The COMClient object has the following properties and methods:

– Properties

Property Type Description

State EClientState The state of the Client. It can be connected or disconnected.

EventMask ULONG The Event Mask settings determine what events are displayed in
the audit trail and which are ignored. The masks involve
changing the bits corresponding to what events you want set.
The Event Cache flag allows you to retrieve the audit trail from
SiPass integrated prior to logging in with your 3rd party
application. This needs to be set before connecting.

Event Cache 0x00000001

Generic Events 0x00000002
Database Events 0x00000004
Access Events 0x00000008
State Events 0x00000010
Alarm Events 0x00000020
 Object Reference

– Methods

Method Arguments Description

Connect Connects to SiPass integrated and logs the operator in.

Operator The operator’s login name

Password The operator’s password

Disconnect None Disconnects from SiPass integrated and logs the operator out.

Process Processes objects passed to the Client. These may include

Manual Command objects or Alarm Action objects.

Object This is an object consisting of an Alarm Action or Manual

Command that needs to be processed by the Client object.

GetByID Returns an object of the specified object ID and type.

Type The type of object required.

ObjID The ID number of the object required.

GetByType Returns all objects of the specified type.

Type The type of object(s) required.

GetBySubType Returns all objects of the specified subtype.

SubType The Subtype of the object(s) required

GetRelatives Returns objects by their relation to another object. Used for

retrieving the object hierarchy in the system and to retrieve the
status of objects.

Type The type of object(s) required.

ObjID The ID number of the object that the search is based on.
Note: If retrieving the status, using an ObjID value of 0 means
the status of all objects of specified type will be retrieved.

ERelation enum The relation between the objects that is required (child, parent or
value status)

CheckPrivilege Checks the privilege of the current operator against specified

privileges and levels to see if a certain action is allowed.

EOpPrivilege The privilege type: Events, Alarms or Commands

enum value

EPrivLevel enum The privilege levels: View, Modify or Create. Not all levels are
value possible with all privileges (for example you cannot modify or
create alarms).

Subscribe Subscribe to the subscription based events

EObjType Subscription type to which to subscribe. Eg. Counter, Timer or

APBArea

LONG ObjectID of the Point to subscribe (here point is used to describe

the Counter, Timer or APBArea type points

Unsubscribe Unsubscribe from the subscription based events

EObjType Subscription type from which to unsubscribe. Eg. Counter, Timer

or APBArea

LONG ObjectID of the Point to unsubscribe (here point is used to

describe the Counter, Timer or APBArea type points

19
Smart Infrastructure A-100026-1
Object Reference

– Events

Event Type Description

OnClientState State This event triggers on a notification of client state change.

OnEvent Events This event triggers on a notification of an event.

OnAlarm Alarm This even triggers on a notification of an alarm.

OnSubscriptionEvent SubscriptionEvent This event triggers on a notification of subscription based

events from Counter/Timer/APBArea status changes (Eg.
counter value changed, timer value changed, APBArea
count changed or runtime APBArea mode changed)

➔ Example

– Connect to SiPass integrated Server

The basis for communication with the SiPass integrated server is the COMClient
object. This is the main class that provides access to all other objects. The sample
application creates an instance of the COMClient object and logon to the SiPass
integrated server before any other activities.

1. Create an instance of the COMClient object

2. Connect using the operator's credentials.
a. If the login was successful, the client’s state property should be
EClientState.eConnected.
b. If the login was unsuccessful, an exception will be thrown.
3. Disconnect from SiPass integrated when the application finishes.

COMClient client = new COMClient();

// Get operator credentials.
client.Connect(name, pwd);

if(client.State == EClientState.eConnected)
{
// We are connected.
// Disconnect when finished.
client.Disconnect();
}

– Querying the SiPass integrated Hardware Configuration

The SiPass integrated hardware component tree is created by using the

GetByType and GetRelatives methods of the COMClient object as follows:

4. Start by retrieving the server object.

Array server = client.GetByType(EObjType. eServer, null);

// ... Process buses returned.

5. Load children of the server object recursively.

Array children = client.GetRelatives(component.Type,

component.ID, ERelationship.eChildren, null);
 Object Reference

– Querying Objects

An object can be obtained by using the GetByID method of the COMClient object
as follows:

1. Query the component passing object type and id.

2. Verify the object type returned.
3. View details of the object returned.

int objectID = 1;
EObjType type = EObjType.eBus;

// Query the component object by id.

object component = client.GetByID(type, objectID);

// Verify object type.

if(component is IBus)
{
// View details of bus
}

– Alarm Notifications

Alarm notifications can be obtained via the OnAlarm event of the COMClient
object as follows:

1. Add an event handler to receive alarm notifications.

client.OnAlarm += new _ _
_ICOMClientEvents_OnAlarmEventHandler(_client_OnAlarm);

2. Implement event handler.

3. Display alarm.

private void _client_OnAlarm(Alarm alarm)

{
if(alarm.State == EAlarmState.eAlarmNormal)
{
// Remove alarm from list.

}
else
{
// If already shown update alarm status,
// otherwise display alarm in alarm list.
}
}

21
Smart Infrastructure A-100026-1
Object Reference

6.2 Generic Object

The Generic object is a template for the general object properties.
The interface for this object is: IGenericObj
The Generic object has the following properties.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID number of the object.

Name BSTR The name of the object.

6.2.1 Example

The following example retrieves all objects configured in SiPass integrated and
displays the details for generic objects:

Array objects = Client.GetByType(EObjType.eAllObjects, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IGenericObj)
{
IGenericObj genericObj = (IGenericObj) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3}", genericObj.ID, genericObj.Type,
genericObj.SubType, genericObj.Name);
}
}
}
 Object Reference

6.3 Server Info Object

The Server Info object provides information about the SiPass integrated server.
The interface for this object is: IServer
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

6.3.1 Example

The following example shows the use of the Server Info object:

Array serverArray = Client.GetByType(EObjType.eServer, null);

// If the query was succesful an array with one element
should be returned.
if(serverArray != null && serverArray.Length == 1 &&
serverArray.GetValue(0) is IServer)
{
IServer server = (IServer)serverArray.GetValue(0);
Console.WriteLine("ID:{0} Type:{1} SubType:{2} Name:{3}",
server.ID, server.Type, server.SubType, server.Name);
}

23
Smart Infrastructure A-100026-1
Object Reference

6.4 Bus Object

The Bus object provides information about the selected bus.
The interface for this object is: IBus
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

6.4.1 Example

The following example shows how to access the Bus object:

Array objects = Client.GetByType(EObjType.eBus, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IBus)
{
IBus bus = (IBus) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3}", bus.ID, bus.Type, bus.SubType, bus.Name);
}
}
}
 Object Reference

6.5 Unit Object

The Unit object provides information about the selected ACC.
The interface for this object is: IUnit
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

Timezone __int64 The Timezone of the ACC. -1 means zone is invalid.

StdTzName BSTR Standard timezone name

TzDisplayName BSTR User-friendly timezone name (Time shift, cities)

6.5.1 Example

The following example shows how to use the Unit object:

Array objects = Client.GetByType(EObjType.eUnit, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IUnit)
{
IUnit unit = (IUnit) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3}", unit.ID, unit.Type, unit.SubType,
unit.Name);
}
}
}

25
Smart Infrastructure A-100026-1
Object Reference
6.6 FLN Object

The FLN object provides information about the selected FLN.

The interface for this object is: IFLN
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

6.6.1 Example

The following example shows how to use the FLN object:

Array objects = Client.GetByType(EObjType.eFLN, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IFLN)
{
IFLN fln = (IFLN) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3}", fln.ID, fln.Type, fln.SubType,
fln.Name);
}
}
}
 Object Reference

6.7 Device Object

The Device object provides information about the Devices.
The interface for this object is: IDevice
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience. It has one method that retrieves the Door Set
status.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

DoorSet EDoorSetType The door set combination. For example Dual Reader DRI

– Methods

Method Argument Description

GetDoorSets DoorSets Retrieves the Door Set from the device.

6.7.1 Example

The following example shows how to use the Device object:

Array objects = Client.GetByType(EObjType.eDevice, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IDevice)
{
IDevice device = (IDevice) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3} DoorSet:{4}", device.ID, device.Type,
device.SubType, device.Name, device.DoorSet);
}
}
}

27
Smart Infrastructure A-100026-1
Object Reference
6.8 Hub Object
The Hub object provides information about the selected Hub.
The interface for this object is: IHUB
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

 Object Reference
6.9 Door Set Object
A Door Set is a collection of points that represent a door. A DRI could have one or
two doors depending on its configuration. In single door configuration the door will
consist of two readers, latch, door frame and passback.
The interface for this object is: IDoorSet
The Door Set object has the following properties. A value of zero means that no
point of that type exists.

– Properties

Property Type Description

DoorNumber LONG The number assigned to the Door.

Reader1 LONG Point ID for Door Reader one.

Reader2 LONG Point ID for Door Reader two.

DoorFrame LONG Point ID of the Door Frame Point.

Passback LONG Point ID of the Passback Point.

Latch LONG Point ID of the Door Latch Point.

6.9.1 Example

The following example shows how to use the Door Set object:

Array doors = device.GetDoorSets();

if(doors != null)
{
foreach(IDoorSet doorSet in doors)
{
Console.WriteLine("DoorFrame:{0} Latch:{1} Passback:{2}
Reader1:{3} Reader2:{4}",
doorSet.DoorFrame, doorSet.Latch, doorSet.Passback,
doorSet.Reader1, doorSet.Reader2);
}
}

29
Smart Infrastructure A-100026-1
Object Reference

6.10 Point Object

The Point object provides information about the points in the system.
The interface for this object is: IPointObj
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

OpMode EPointOpMode The current operation mode of the point.

6.10.1 Example

The following example shows how to use the Point object:

Array objects = Client.GetByType(EObjType.ePoint, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IPointObj)
{
IPointObj point = (IPointObj) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3} OpMode:{4}", point.ID, point.Type,
point.SubType, point.Name, point.OpMode);
}
}
}
 Object Reference

6.11 Area Object

The Area object provides information about the selected Area.
The interface for this object is: IArea
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

UnitID LONG The ID of corresponding unit

ShortName BSTR The short name of the area.

Type
- eArea

SubType can be
- eIntrusionArea
- eSintonyIntrusionArea
- eSPCIntrusionArea

6.11.1 Example

Array objects = Client.GetByType(EObjType.eArea, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IArea)
{
IArea area = (IArea) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3} UnitID:{4}", area.ID, area.Type,
area.SubType, area.Name, area.UnitID);
}
}
}

31
Smart Infrastructure A-100026-1
Object Reference
6.12 Flag Object
The Flag object provides information about the selected Flag.
The interface for this object is: IFlag
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

Unit ID LONG The ID of the unit the flag belongs to.

UnitName BSTR The name of the unit the flag belongs to.

DefaultValue VARIANT The default value of the flag.

_BOOL

AuditTrailReporting VARIANT Shows if flag events are being reported to SiPass.

_BOOL

Type
- eFlag
SubType
- eNoSubType

6.12.1 Example

The Following example shows how to use the Flag Object:

Array objects = Client.GetByType(EObjType.eFlag, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IFlag)
{
IFlag flag = (IFlag) component;
Console.WriteLine("ID: {0} Type: {1} SubType: {2}
Name: {3}",
flag.ID, flag.Type, flag.SubType,
flag.Name);
}
}
}
 Object Reference
6.13 Counter Object
The Counter object provides information about the selected Counter.
The interface for this object is: ICounter
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.
– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

UnitID LONG The ID of the unit the counter belongs to.

UnitName BSTR The name of the unit the counter belongs to.

DefaultValue LONG The default value of the counter.

PresetValue LONG The preset value of the counter.

MaxValue LONG The maximum value of the counter.

CountMode ECounterMode The incrementing/decrementing behaviour of the counter.

See the chapter 'Enumerator Explanation' for a
description of ECounterMode values.

AuditTrailReporting VARIANT_BOOL Shows if counter events are being reported to SiPass

server.

Type
- eCounter
SubType
- eNoSubType

6.13.1 Example

The Following example shows how to use the Counter Object:

Array objects = Client.GetByType(EObjType.eCounter, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is ICounter)
{
ICounter counter = (ICounter) component;
Console.WriteLine("ID: {0} Type: {1} SubType: {2}
Name: {3}",
counter.ID, counter.Type,
counter.SubType, counter.Name);
}
}
}

33
Smart Infrastructure A-100026-1
Object Reference
6.14 Timer Object
The Timer object provides information about the selected Timer.
The interface for this object is: ITimer
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

UnitID LONG The ID of the unit the timer belongs to.

UnitName BSTR The name of the unit the timer belongs to.

Period LONG The period (in milliseconds) of the timer.

TimerMode ETimerMode The behaviour of the timer while running. See the chapter
'Enumerator Explanation' for a description of ETimerMode
values.

AuditTrailReporting VARIANT_BOOL Shows if counter events are being reported to SiPass

server.

Type
- eTimer
SubType
- eNoSubType

6.14.1 Example

The Following example shows how to use the Timer Object:

Array objects = Client.GetByType(EObjType.eTimer, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is ITimer)
{
ITimer timer = (ITimer) component;
Console.WriteLine("ID: {0} Type: {1} SubType: {2}
Name: {3}",
timer.ID, timer.Type,
timer.SubType, timer.Name);
}
}
}
 Object Reference
6.15 Anti-Passback Cluster
The APBCluster object provides information about the selected Anti-Passback
Cluster.
The interface for this object is: IAPBCluster
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

Type
- eAPBCluster
SubType
- eGeneric

6.15.1 Example

The Following example shows how to use the Anti-Passback Cluster Object:

Array objects = Client.GetByType(EObjType.eAPBCluster, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IAPBCluster)
{
IAPBCluster cluster = (IAPBCluster) component;
Console.WriteLine("ID: {0} Type: {1} SubType: {2}
Name: {3}",
cluster.ID, cluster.Type,
cluster.SubType, cluster.Name);
}
}
}

35
Smart Infrastructure A-100026-1
Object Reference
6.16 Anti-Passback Area
The APBArea object provides information about the selected Anti-Passback Area.
The interface for this object is: IAPBArea
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

MaxCardholders LONG The maximum number of cardholders allowed in

the anti-passback area.

EnforceMaxCardholders VARIANT_BOOL Whether additional cardholders will by physically

allowed into the anti-passback area if the
maximum number is reached.

Type
- eAPBArea
SubType
- eHardAntiPassbackArea
- eSoftAntiPassbackArea
- eFailSoftAntiPassbackArea
- eTimedReEntryArea
- eNoAntiPassbackArea

6.16.1 Example

The Following example shows how to use the Anti-Passback Area Object:

Array objects = Client.GetByType(EObjType.eAPBArea, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IAPBArea)
{
IAPBArea area = (IAPBArea) component;
Console.WriteLine("ID: {0} Type: {1} SubType: {2} Name: {3}",
area.ID, area.Type, area.SubType, area.Name);
}
}
}
 Object Reference
6.17 Bank Object
The Bank object provides information about the bank and floor configurations.
The interface for this object is: IBanks
All the properties of the object are inherited from the Generic object. They have
been reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

ID LONG The ID Number of the object.

Name BSTR The name of the object.

Type
– eBanks

SubType
– eBankGeneric - native banks

– eBankDestinationControl - TKE banks

6.17.1 Example

The following example shows how to use the Bank object:

Array objects = Client.GetByType(EObjType.eBanks, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IBanks)
{
IBanks bank = (IBanks) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3}", bank.ID, bank.Type, bank.SubType,
bank.Name);
}
}
}
2

37
Smart Infrastructure A-100026-1
Object Reference
6.18 External System Object
The External System object provides information about the selected external
system.
The interface for this object is: IExternalSystem
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties
`

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

6.19 External System Point Object

The External System Point object provides information about the selected external
system point.
The interface for this object is: IExternalSystemPoint
All of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

 Object Reference
6.20 SubscriptionEvent Object
The SubscriptionEvent object provides all the details about subscription based
events sent from the SiPass system. These events are only sent for subscribed
ojects.
The interface for this object is: ISubscriptionEvent
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object.

SubType ESubType The subtype of the object.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred.

Description BSTR A short description of the event (if available).

Location BSTR The exact location of the event (if available).

Object ID LONG The returned value of the subscribed object.

ObjectType ESubscriptionType The type of subscribed object

ValueState LONG The returned value of the subscribed object

(E.g. counter value if counter object type).

ValueStateType EsubscribedValueType The value type of the subscribed object to be

returned (E.g, Long if counter).

6.20.1 Example

Subscription based object changes can be received via the ISubscriptionEvent

object.
Use this event to update the state of an object if it is currently being displayed.
Example:
public void ShowStatus(ISubscriptionEvent objState)
{
statusBox.Visible = true;
timestamp.Text = objState.Timestamp.ToString();
location.Text = objState.Location;
description.Text = objState.Description;

39
Smart Infrastructure A-100026-1
Object Reference

if (objState.SubType == ESubType.eAPBAreaModeValue)
{
EAPBAreaMode apbMode = EAPBAreaMode.eAPBAreaUnknownMode;
apbMode = (EAPBAreaMode)objState.ValueState;
currentMode.Text = apbMode.ToString();
}
else if (objState.SubType == ESubType.eAPBAreaCounterValue)
areaCounter.Text = objState.ValueState.ToString();}

Note:
– If either or both of APBAreaState changes (APB area count change or APB area runtime mode
change) occur, then two subscription events are dispatched. One that contains the APB area count
value and another that contains the APB area runtime mode.
 Object Reference
6.21 Alarm Class Object
The Alarm Class object provides information about the Alarm Classes in the
system and associated Instructions.
The interface for this object is: IAlarmClass
Most of its properties are inherited from the Generic object. They have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The ID Number of the object.

Name BSTR The name of the object.

Instruction BSTR The instructions for the operator to take when the alarm
appears.

6.21.1 Example

The following example shows how to use the Alarm Class object:

Array objects = Client.GetByType(EObjType.eAlarmClass, null);

if(objects != null)
{
foreach(object component in objects)
{
if(component is IAlarmClass)
{
IAlarmClass alarmClass = (IAlarmClass) component;
Console.WriteLine("ID:{0} Type:{1} SubType:{2}
Name:{3} Instruction:{4}", alarmClass.ID,
alarmClass.Type, alarmClass.SubType, alarmClass.Name,
alarmClass. Instruction);
}
}
}

41
Smart Infrastructure A-100026-1
Object Reference
6.22 Generic Event Object
The Generic Event Object provides all the details about generic events in the
system. This information is displayed in the audit trail and is the basis for other
event reporting.
The interface for this object is: IGenericObj
The Generic Event object has the following properties:
– Properties

Property Type Description

Type EObjType The type of the event.

SubType ESub Type The subtype of the event.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred

Description BSTR A short description of the event.

Location BSTR The exact location of the event.

EventID LONG An optional ID number assigned to the event.

6.22.1 Example

Event notifications can be obtained via the OnEvent event of the COMClient
object as follows:

1. Add an event handler to receive event notifications.

client.OnEvent+= new _
_ICOMClientEvents_OnEventEventHandler(_client_OnEvent);

2. Implement event handler.

3. The client might return one or more event notifications.
4. All the notifications returned can be of type IGenericEvent, IDBEvent,
IAccessEvent and IObjState. These interfaces should be queried to process the
events accordingly.

private void _client_OnEvents(Array events)

{
foreach(object eventObject in events)
{
if(eventObject is IGenericEvent)

// Process generic event as Audit Trail

}

if(eventObject is IDBEvent)
{
// Process database event
}
else if(eventObject is IAccessEvent)
{
// Process access event
}
else if(eventObject is IObjState)
{
// Process state change event
}
}
}
 Object Reference
6.23 Database Event Object
The Database Event object provides all the details about database events in the
system. This information is displayed in the audit trail if the event mask is set to
display it.
The interface for this object is: IDBEvent
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the event.

SubType ESub Type The subtype of the event.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred

Description BSTR A short description of the event.

Location BSTR The exact location of the event.

EventID LONG An optional ID number assigned to the event.

ObjectType EObjType Object Type.

ObjectID LONG Object ID

6.23.1 Example

Database events can be received via the IDBEvent object. The event provides
information related to database changes on SiPass integrated objects.
Use this event to update alarms when an Alarm class is modified and to keep the
component tree up to date with changes in the server.

private void ProcessDBEvent(IDBEvent dbEvent)

{
switch(dbEvent.SubType)
{
case ESubType.eDBCreate:
// Add new object to component tree.
break;

case ESubType.eDBModify:
// Modify new object in component tree.
break;

case ESubType.eDBDelete:
// Remove the object from the tree.
break;

default:
break;
}
}

43
Smart Infrastructure A-100026-1
Object Reference
6.24 State Object
The State object provides all the details about state events in the system. This
information is displayed in the audit trail if the event mask is set to display it.
The interface for this object is: IObjState
This object inherits all the properties of the Generic object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the event.

SubType ESub Type The subtype of the event.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred

Description BSTR A short description of the event.

Location BSTR The exact location of the event.

EventID LONG An optional ID number assigned to the event.

ObjectType EObjType Object type that is changing state.

ObjectID LONG Object ID

State EObjState The new object state.

StateType EStateType The state type of the object. It can be either Alarm or
Normal.

PointDisabledState EPointDisabledState Indicates whether the point is enabled or disabled.

Supported for access, input and output points.

CommsStatus ECommsStatus Indicates whether the point is online or offline.

Currently supported only for access points.

6.24.1 Example

State change events can be received via the IObjState object.

Use this event to update the state of an object if it is currently being displayed.

public void ShowStatus(IObjState objState)

{
if(objState.State != eObjState.eStateUnknown)
{
statusBox.Visible = true;
state.Text = objState.State.ToString();
stateType.Text = objState.StateType.ToString();

timestamp.Text = objState.Timestamp.ToString();

location.Text = objState.Location;
description.Text = objState.Description;
}
}
 Object Reference

The state of an object (or multiple objects) can be queried by using the the
GetRelatives method of the COMClient object as follows:

1. Query the state passing object type, id and ERelation.eStatus as

relationship type.
2. If the query was successful, an array with the status object will be returned. If
an id of 0 was passed in, an array with the status of all objects of the
specified object type will be returned.
3. Verify the object type returned.
4. View the state of the object returned.

public void QueryStatus(_genericObj genericObj)

{
// Query the unit status passing the id of the unit.
Array stateArray =
MainForm.Client.GetRelatives(genericObj.Type,
genericObj.ID, ERelation.eStatus, null);

// If the query was successful an array with one element

// should be returned.
if(stateArray != null && stateArray.Length == 1 &&
stateArray.GetValue(0) is IObjState)
{
IObjState state = (IObjState)stateArray.GetValue(0);
//... Show the state.
}
}

6.24.2 State limitations for External System Points

For object types "External System" and "External System Point", due to differences
in SALTO event retrieval compared to ACC, the state is only persisted in SiPass
system if an alarm class is configured for the SALTO system / point in SiPass
integrated containing relevant states intended to be tracked. This will affect any
queries for status done with the GetRelatives() call with parameter
ERelation.eStatus.

45
Smart Infrastructure A-100026-1
Object Reference
6.25 APB Area State Object

The APB Area State object provides all the details about APB Area state events in
the system. This information is displayed in the audit trail if the event mask is set to
display state events.

The APB Area State object is used in the API as there can be multiple states held
by an APB area simultaneously. Multiple simultaneous states are not represented
in a normal State Object.

The interface for this object is: IAPBAreaObjState. This interface extends the
IObjState interface.

This object inherits all the properties of the State object, and the following 3
properties available in IAPBAreaObjState:
– Properties

Property Type Description

FourEyesState EObjState Four Eyes Alarm/Normal State of the APB Area. This
could be eAPBAreaFourEyesAccessAlarm or
eAPBAreaFourEyesAccessNormal.

WorkgroupCapacityState EObjState Workgroup Capacity state of the APB Area. This could
be any of the following EObjState enums:
• eAPBAreaWorkgroupCapacityFull
• eAPBAreaWorkgroupCapacityExceeded
• eAPBAreaWorkgroupCapacityNotFull
• eAPBAreaWorkgroupCapacityEmpty
• eAPBAreaWorkgroupCapacityNotEmpty

GeneralApbAreaState EObjState All other states of an APB Area, mostly general area
capacity states

6.25.1 Example

State change events can be received via the IObjState object.

Use this event to update the state of an object if it is currently being displayed.
Check to see if we can cast to IAPBAreaObjState to access extra properties for
APB Area states. This should be possible if the object being referenced is an APB
Area.
public void ShowStatus(IObjState objState)
{
IAPBAreaObjState apbObjState = objState as
IAPBAreaObjState;
if (apbObjState != null)
{
generalAreaStateTextbox.Text =
apbObjState.GeneralApbAreaState.ToString();
workgroupCapacityTextbox.Text =
apbObjState.WorkgroupCapacityState.ToString();
fourEyesStateTextbox.Text =
apbObjState.FourEyesState.ToString();
}
}
 Object Reference
The state of an APB Area can be queried by using the the GetRelatives method of
the COMClient object as follows:
1. Query the state passing object type (eAPBArea), id and
ERelation.eStatus as relationship type.
2. If the query was successful, an array with the status object will be
returned.
3. Verify the object type returned.
4. View the state of the object returned.

public void QueryStatus(_genericObj genericObj)

{
// Query the APB Area status passing the id of the APB
Area.
Array stateArray =
MainForm.Client.GetRelatives(genericObj.Type,
genericObj.ID, ERelation.eStatus, null);
// If the query was successful an array with one element
// should be returned.
if(stateArray != null && stateArray.Length == 1 &&
stateArray.GetValue(0) is IAPBAreaObjState)
{
// IAPBAreaObjState interface should be exposed in
object returned
IAPBAreaObjState state =
(IAPBAreaObjState)stateArray.GetValue(0);

//... Show the state.

}
}

47
Smart Infrastructure A-100026-1
Object Reference
6.26 Access Event Object
The Access Event Object provides all the details about access events in the
system. This information is displayed in the audit trail if the event mask is set to
display it.
The interface for this object is: IAccessEvent
This object inherits all the properties of the State object which have been
reproduced here for convenience.
– Properties

Property Type Description

Type EObjType The type of the event.

SubType ESub Type The subtype of the event.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred

Description BSTR A short description of the event.

Location BSTR The exact location of the event.

EventID LONG An optional ID number assigned to the event.

ObjectType EObjType Object Type that is changing state.

ObjectID LONG Object ID Number for the object changing state.

State EObjState Object State for state change.

StateType EStateType The type of object state being changed into.

PointDisabledState EPointDisabledState Indicates whether the point is enabled or disabled.

Supported for access, input and output points.

CommsStatus ECommsStatus Indicates whether the point is online or offline.

Currently supported only for access points.

CardNumber BSTR The Card Number of the access event.

Facility LONG The Facility ID of the access event.

CardTech LONG The Card Technology reported by the access event.

FirstName BSTR The First Name of the cardholder from the access
event.

LastName BSTR The Last Name of the cardholder from the access
event.

6.26.1 Example

The following example shows how to use the Access Event object:

if(eventObject is IAccessEvent)
{
IAccessEvent accessEvent = (IAccessEvent)eventObject;
Console.WriteLine("CardNumber:{0} CardTech:{1} Facility:{2}
FirstName:{3} LastName:{4}", accessEvent.CardNumber,
accessEvent.CardTech, accessEvent.Facility,
accessEvent.FirstName, accessEvent.LastName);
}
 Object Reference
6.27 Alarm Object
The Alarm Object provides all the details about alarm events in the system. This
information is displayed in the audit trail if the event mask is set to display it.
The interface for this object is: IAlarm
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the event.

SubType ESub Type The subtype of the event.

Timestamp DATE The timestamp of the event.

ServerTime DATE The server time when the event occurred

Description BSTR A short description of the event.

Location BSTR The exact location of the event.

EventID LONG An optional ID number assigned to the event.

Priority LONG The Alarm Priority of the alarm event.

Count LONG The number of alarms triggered for this alarm event.

State EAlarmState The state of the alarm. States can be unknown, active, actioned,
restored, reactivated (after time), and normal.

AlarmClassID LONG The ID of the alarm class assosciated with this alarm.

6.27.1 Example

The following example shows how to use the Alarm object:

Array alarms = _client.GetByType(EObjType.eAlarm, null);

if(alarms != null)
{
foreach(Alarm alarm in alarms)
{
Console.WriteLine("Priority:{0} Timestamp:{1} Facility:{2}
State:{3} Description:{4}", alarm.Priority,
alarm.Timestamp, alarm.State, alarm.Description);
}
}

49
Smart Infrastructure A-100026-1
Object Reference
6.28 Alarm Action Object
The Alarm Action object is used by the operator to send an alarm
acknowledgement to the SiPass server.
The interface for this object is: IAlarmAction

– Properties

Property Type Description

AlarmID LONG The ID number associated with the alarm.

Action BSTR The alarm action description input by the operator. The maximum
supported length is 255 characters

6.28.1 Example

Alarm acknowledgments can be sent to the client via the Process method of the
COMClient object as follows:

1. Create an alarm action object

AlarmAction action = new AlarmAction();

2. Specify the alarm id and action.

action.Action = "Action";
action.AlarmID = Alarm.EventID();

3. Send acknowledgement.

client.Process(action);
 Object Reference
6.29 Manual Command Object
The “Manual Command” Object allows the operator to send manual commands via
the Management Station API. These commands are processed by the client object.
The interface for this object is: IManualCommand

– Properties

Property Type Description

ObjectID LONG The ID number associated with the object that is receiving the
command.

ObjectType EObjType The type of the object that is receiving the command.

Command ECommand The command being sent to the object.

Parameter BSTR Parameters associated with the manual command.

6.29.1 Example

The following example shows how to use the Manual Command object:

Manual commands can be sent to the client via the Process method of the
COMClient object as follows:

1. Create a Manual Command object

ManualCommand manualCommand = new ManualCommand();

2. Specify the command type, object id, object type and any optional arguments.

manualCommand.Command = ECommand.eOutAllowAccess;
manualCommand.ObjectID = objectID;
manualCommand.ObjectType = type;

3. Send command.

client.Process(manualCommand);

51
Smart Infrastructure A-100026-1
Object Reference
6.30 OSS-SO Sites Object
The “OSSSOSites” object provides information about the selected OSS-SO Sites
parent object.
The interface for this object is: IOSSSOSites
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience.

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The database id of the object

Name BSTR The name of the object

– Type

eOSSSOSites

– SubType

eGeneric
 Object Reference
6.31 OSS-SO Site Object
The “OSSSOSite” object provides information about the selected single OSS-SO
Site object.
The interface for this object is: IOSSSOSite
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The database id of the object

Name BSTR The name of the object

SiteId LONG OSS-SO Customer Site ID

SmartcardProfile BSTR Name of the Smartcard Profile set for this

OSS-SO Site

RevalidationPeriod LONG Site revalidation period in hours

– Type

eOSSSOSite

– SubType

eNoSubType

53
Smart Infrastructure A-100026-1
Object Reference
6.32 OSS-SO Reader Object
The “OSSSOReader” object provides information about the selected
OSSSOReader object.
The interface for this object is: IOSSSOReader
This object inherits all the properties of the Generic Event object which have been
reproduced here for convenience

– Properties

Property Type Description

Type EObjType The type of the object

SubType ESubType The subtype of the object

ID LONG The database id of the object

Name BSTR The name of the object

DoorId LONG The OSS-SO Door ID associated with this reader

– Type

eOSSSOReader

– SubType

eNoSubType
 Code Samples

7 Code Samples
This section introduces a working application which uses the Management Station
API. The executable files and code samples supplied are in the form of Microsoft
Visual C#

Note:
– SiPass integrated must be installed on the computers on which you want to run the sample
application

7.1 SiPass integrated Management Station Test Program

The sample application demonstrates how the Management Station API features
can be used in a real life scenario. The application provides an overview of the
SiPass integrated hardware configuration and monitors events, alarms and
database updates happening in the system. It also provides the ability to send
manual commands.

Fig. 1 SiPass integrated Management Station Test Program

7.2 Source Files

The source for the sample application is available in the SiPass integrated API
and RESTful API folder in the SiPass integrated Software bundle.

55
Smart Infrastructure A-100026-1
8 Appendix A: Error Codes
The Management Station API can generate the following errors:
Name Value Description
ADV_E_USER_NAME 0x80040A01 Invalid username
ADV_E_PASSWORD 0x80040A02 Invalid password
ADV_E_LOCKOUT 0x80040A05 Operator lockout
ADV_E_RETRIES_EXCEEDED 0x80040A06 Operator exceeded allowed number of
incorrect logon attempts
ADV_E_EXPIRED 0x80040A07 Operator account expired
ADV_E_INTERVAL 0x80040A08 Operator not allowed to logon at this time
ADV_E_TOO_MANY_CLIENTS 0x80040A0B Too many workstations logged on
ADV_E_SELECT 0x80040A0D Database query error
ADV_E_FETCH 0x80040A0E Error in SQL fetch, no results
ADV_E_NO_LOGON 0x80040A0F No logon was performed
ADV_E_REQUIRED_LICENSE_MANAPI 0x80040A2E MS-API License is required
ADV_E_WRONG_VERSION 0x80040A2F Client/Server version mismatch
ADV_E_PASSWORD_EXPIRED 0x80040A30 Operator password expired
ADV_E_TEMPORARY_LOCKOUT 0x80040A31 Operator temporary lockout
ADV_E_RETRIES_EXCEEDED_TEMPORARY 0x80040A35 Operator exceeded allowed number of
incorrect logon attempts, and account is
temporarily locked.
ADV_E_PASSWORD_OLD_VERSION 0x80040A37 Old password version found in database.
Previous conversion probably failed.
ADV_E_CLIENT_NEEDS_UPDATE 0x80040A62 Client needs to be updated due to server
hotfix
ADV_W_NEW_CLIENT_HF_AVAILABLE 0x80040A63 New client hotfix is available
ADV_E_SQL_STATUS_OFFLINE 0x80040A71 The SiPass integrated server could not
establish a connection with SQL server
E_CCA_RANGE_START 0x80040C00 Start of Error Code Range. Not reported
during operation.
E_CCA_READ_CONFIG 0x80040C01 Error whilst trying to read the configuration
from the registry.
E_CCA_EVENT_HANDLER 0x80040C02 Error setting up the Audit Trail and Event
Handler.
E_CCA_NOT_CONNECTED 0x80040C03 Attempting to perform any operation when
the client is not yet connected or has been
disconnected.
E_CCA_INVALID_TYPE 0x80040C04 An operation has been attempted on a
type that does not support that action.
E_CCA_INVALID_CMD 0x80040C05 An invalid or erroneous manual command
was sent..
E_CCA_CMD_FAILED 0x80040C06 Manual command failed.
E_CCA_NO_PRIV 0x80040C07 Current operator does not have the
privileges to execute that command.
 Appendix A: Error Codes

In addition, there are various Microsoft RPC and COM system error codes that can
be reported during runtime that are not SiPass specific. The most common ones
that may be encountered are listed below

Name Value Description

RPC_S_SERVER_UNAVAILABLE 0x800706BA The RPC server is unavailable
RPC_S_SERVER_TOO_BUSY 0x800706BB The RPC server is too busy to complete this operation
RPC_S_CALL_FAILED 0x800706BE The remote procedure call failed

E_UNEXPECTED 0x8000FFFF Catastrophic failure

E_OUTOFMEMORY 0x8007000E Ran out of memory
E_INVALIDARG 0x80070057 One or more arguments are invalid
E_NOINTERFACE 0x80004002 No such interface supported
E_FAIL 0x80004005 Unspecified error
E_ACCESSDENIED 0x80070005 General access denied error

For more information on various system error codes see these links:
COM system error codes
https://docs.microsoft.com/en-us/windows/desktop/com/com-error-codes-1

RPC system error codes

https://docs.microsoft.com/en-us/windows/desktop/debug/system-error-codes--1700-3999-

57
Smart Infrastructure A-100026-1
Appendix B: Enumeration Definitions

9 Appendix B: Enumeration Definitions

The Object Type (enum EObjType) and Sub Type (enum ESubType) tells us about
the type of point or event the client is dealing with. The descriptions are as follows:

Object Type Sub Type Description

eNoType N/A Unknown/unsupported object type

eAllObjects N/A When used in conjunction with

GetByType, retrieves all supported
objects

eServer eGeneric SiPass integrated Server

eBus (Child relation to Server object)

eACCBus ACC Controller bus
eDialupBus Dialup / Remote Network bus
eCerPassBus CerPass bus

eUnit (Child relation to Bus object)

eACCUnit ACC Unit
eCCZ3124 CerPass CCZ3124 Unit
eCCZ3128 CerPass CCZ3128 Unit
eCCZ3134 CerPass CCZ3134 Unit
eCCZ3138 CerPass CCZ3138 Unit
eCCZ3330 CerPass CCZ3330 Unit
eACCUnit_4 ACC-4 Unit
eACCUnit_8 ACC-8 Unit
eACCUnit_16 ACC-16 Unit
eACCUnit_32 ACC-32 Unit
eACCUnit_Lite ACC-Lite Unit
eACCUnit_G2 ACC-G2 Unit
eACCUnit_Granta ACC-GRANTA Unit
eACCUnit_AP ACC-AP Unit

eFLN (Child relation to Unit object)

eACCFLN ACC FLN
eNTFLN NT FLN
eCerPassFLN CerPass FLN
eEntroFLN Entro FLN
eGrantaFLN Granta FLN
eAPFLN ACC-AP FLN
eAperioFLN Aperio FLN

eDevice (Child relation to FLN object)

eSRI SRI
eDRI DRI
eERI ERI
eOPM OPM
eIPM IPM
eSMI SMI (Smart Card Reader Interface)
e8IO 8IO
eCX8 CX8
eCX23 CX23
eNT8 NT8
eNT8LC NT8LC
eNT161 NT161
eNT182 NT182
eNT190 NT190
eDC12 DC12
eDC22 DC22
eGrantaCotag GRANTA COTAG
 Appendix B: Enumeration Definitions
eGrantaSwipe GRANTA SWIPE
eGrantaIO GRANTA IO
eGrantaBackboard GRANTA BACKBOARD
eIAT IAT
eDRIe DRIe
eAperioBasicLock APERIO BASIC LOCK
eMFI MFI Device

ePoint (Child relation to Device object)

eInputPoint Input Point
eOutputPoint Output Point
eAccessPoint Access Point

eGenericEvent eGeneric Generic events (audit trail). Contains

the base properties for other event
types, like database, access, object
state and alarm events

eDBEvent
eDBCreate Database event where an object was
created
eDBModify Database event where an object was
modified (e.g. name change)
eDBDelete Database event where an object was
deleted

eAccessEvent eAccessPointState Card badge or status change at a

reader
eAPBAreaPointState State event involving APB Area
eIntrusionAreaState State event involving Intrusion Area
eFlagState State event involving Flag
eFloorPointState State event involving Floor
State event involving External System
eExternalSystemState
(Salto)
State event involving External System
eExternalSystemPointState
Point (Door/Locker)
eHubState State event involving Aperio Hub
eObjState
eBusStatus State event involving Bus object
eUnitStatus State event involving Unit object
eDeviceStatus State event involving Device object
eInputPointState State event involving Input Point
eOutputPointState State event involving Output Point
eAccessPointState State event involving Access Point

eAlarm eGeneric Alarm event

eAlarmClass N/A Alarm Class object. (Database events

involving alarm classes will set
ObjectType to eAlarmClass)

eArea Child relation to Areas object

eIntrusionArea Native intrusion area
eSintonyIntrusionArea (External) Sintony Intrusion Area
eSPCIntrusionArea (External) SPC Intrusion Area

eAreas eGeneric Top-level parent object for all types of

intrusion areas. Child relation to Server
object.

eFlag eFlagGeneric Child relation to Flags object

eFlags eGeneric Top-level parent object for all Flag

objects Child relation to Server object

59
Smart Infrastructure A-100026-1
Appendix B: Enumeration Definitions

eCounter eCounterGeneric Child relation to Counters object

eCounters eGeneric Top-level parent object for all Counter

objects
Child Relation to Server object

eTimer eTimerGeneric Child relation to Timers object

eTimers eGeneric Top-level parent object for all Timer

objects Child relation to Server object

eAPBArea If a sub-area, has a child relation to the

parent APB area.
Otherwise, child relation to APBCluster
objects.
eHardAntiPassbackArea Hard Anti-Passback
eSoftAntiPassbackArea Soft Anti-Passback
eFailSoftAntiPassbackArea Fail-Soft Anti-Passback
eTimedReEntryArea Timed Re-Entry
eNoAntiPassbackArea No Anti-Passback

eAPBCluster eGeneric Child relation to APBAreas object

Parent object for applicable APBArea
objects

eAPBAreas eGeneric Top-level parent object for all

APBCluster objects
Child relation to Server object

eSubscriptionEvent eNoSubType Subscription based events (Counter,

eAPBAreaCounterValue Timer, APBArea)
eAPBAreaModeValue
eHub (Child relation to FLN Object).
Communication hub that can be linked
with several wireless Locks/Devices.
eAperio_AH30 Aperio Hub Model AH30 with RS485
Connectivity
eExternalSystems Top-level parent for all external
systems. Child relation to Server
object.
eExternalSystem Child relation to External Systems
object
eSalto SALTO External System
eExternalSystemPoint Child relation to External System
object
eDoor SALTO door
eLocker SALTO Locker
eFreeAssignmentLocker SALTO Free Assignment Locker
eOSSSOSites
eGeneric OSS-SO Sites object, containing
individual OSS-SO Site object(s) under
it, in hierarchy.
Child relation to Server object.
eOSSSOSite
eNoSubType OSS-SO Site, child of
OSS-SO Sites object
eOSSSOReader
eNoSubType OSS-SO Reader, child of
OSS-SO Site object
Issued by © Siemens Switzerland Ltd, 2021
Siemens Switzerland Ltd Technical specifications and availability subject to change without notice.
Smart Infrastructure
Global Headquarters
Theilerstrasse 1a
CH-6300 Zug
+41 58 724 2424
www.siemens.com/buildingtechnologies

Document no. A-100026-1 Management Station-API Programmer’s Reference Manual

Edition 05.2021 Smart Infrastructure