AMWorks® Software Matrix API
(Application Programming Interface)
User Guide
Avocent, the Avocent logo, OSCAR, AMX and AMWorks are registered trademarks of Avocent
Corporation or its affiliates. All other marks are the property of their respective owners.
© 2006 Avocent Corporation. All rights reserved. 590-633-501A
ii
T A B L E O F C ON T E N T S
Introduction ....................................................................................................................................... 1
Glossary ............................................................................................................................................. 2
Defines ............................................................................................................................................... 2
Structures ........................................................................................................................................... 3
User permissions ........................................................................................................................ 3
User details................................................................................................................................. 3
Server details .............................................................................................................................. 3
Calls ................................................................................................................................................... 4
LoginAdministrator .................................................................................................................... 4
LogoutAdministrator .................................................................................................................. 6
AddMatrixUser ........................................................................................................................... 7
DeleteMatrixUser ....................................................................................................................... 8
UpdateMatrixUser...................................................................................................................... 8
AssignMatrixUserPermissions ................................................................................................. 10
ClearMatrixUserRights ............................................................................................................ 12
GetMatrixUserList.................................................................................................................... 13
GetMatrixServerList ................................................................................................................. 14
GetMatrixUserRights................................................................................................................ 15
GetMatrixListHead ................................................................................................................... 17
GetMatrixListNext .................................................................................................................... 17
MatrixGetLastError.................................................................................................................. 18
GetMgrVersion ......................................................................................................................... 24
GetApiVersion........................................................................................................................... 25
iii
AMWorks Software Matrix API User Guide
iv
LIST OF TABLES
Table 1: Parameters for the UpdateMatrixUser Call ....................................................................... 9
Table 2: Error Codes for All Calls .................................................................................................. 18
Table 3: Error Codes for LoginAdministrator ................................................................................ 18
Table 4: Error Codes for LogoutAdministrator .............................................................................. 19
Table 5: Error Codes for AddMatrixUser ....................................................................................... 19
Table 6: Error Codes for DeleteMatrixUser ................................................................................... 20
Table 7: Error Codes for UpdateMatrixUser.................................................................................. 20
Table 8: Error Codes for AssignMatrixUserPermissions ............................................................... 21
Table 9: Error Codes for GetServerList .......................................................................................... 22
Table 10: Error Codes for GetUserList........................................................................................... 22
Table 11: Error Codes for GetUserRights ...................................................................................... 22
Table 12: Error Codes for ClearUserRights ................................................................................... 23
Table 13: Error Codes for GetMgrVersion ..................................................................................... 23
Table 14: Error Codes for GetApiVersion ...................................................................................... 24
v
AMWorks Software Matrix API User Guide
1
AMWorks® Software Matrix API
User Guide
Introduction
The AMWorks software Matrix Application Programming Interface (API) allows you to develop or
customize third party applications to work with the AMWorks® Java-based system administration
tool. By utilizing the API, you can program the application to log the Administrator in or out, add or
delete users, change a username or password, modify user rights or compile specific information
about the matrix system. This gives advanced control and flexibility to administrators where they
need it most.
This user guide describes the set of calls provided by the API in the MatrixApi.dll file. The third
party application must use the provided Dynamic Link Library (DLL) for network communications
and interfacing to the AMWorks software. The DLL must be statically linked with this application
using the import library and header file provided. The following three files are required for the API:
•
MatrixApi.h - The header file that contains the API function prototypes, constant defines and
structure declarations. This file must reside in the include path and be included in the
application (for example, #include "MatrixApi.h"). This user guide is intended to be used
together with the MatrixApi.h file.
•
MatrixApi.lib - This is the import library allowing the linker to include the DLL interface code
so API calls are transparent and can be used as if they were local function calls. The
application must link with this library.
•
MatrixApi.dll - This is the dynamic link library that contains the API code. The application is
able to interface with this DLL because of the import library. This file must reside in the path
where the application can find it.
The MatrixApi.h and MatrixApi.lib files are only used when building third party applications. The
MatrixApi.dll file is used each time the application runs and must be physically available to the
application for the matrix system to work.
All function argument strings, unless noted otherwise, are required to be UNICODE (two
bytes per character) strings with Little Endian storage. They are typed in the function argument list
as PUSHORT (unsigned short*).
2
AMWorks Software Matrix API User Guide
NOTES: - The AMWorks software must be running to use this API.
- The AMX switching system and AMWorks software must be synchronized to use this API.
- Some examples in this guide use the Microsoft® Foundation Classes.
Glossary
The following terms are used throughout this documentation:
•
Application Programming Interface (API) – An advanced programming interface provided
with the AMWorks software. System administrators can use the API to develop third party
applications that work with the matrix system.
•
Application – a standalone, third party program that can be manipulated to work with the
matrix system using the API.
•
Matrix system – The AMX switching system and the AMWorks software.
•
Switch – Equipment that provides KVM connectivity to attached target devices.
•
Switching system – A set of switches and attached target devices, user stations, IQ modules
and peripheral devices.
•
Target device – Equipment such as a server or serial device that is attached through an IQ
module to a switch or user station and can be accessed through the switching system.
•
User – A username that has been added to the matrix system. Each user has a normal password
or blank password and specific access rights. System administrators can use the API to manage
users in the matrix system.
Defines
To make code more readable, certain defines are required. These defines are contained in the
MatrixApi.h file and are repeated here.
Rights
Rights are the permissions that an individual user can have to a target device.
USER_RIGHTS_NONE - Value for no rights.
USER_RIGHTS_VIEW - Value for view-only rights.
USER_RIGHTS_FULL - Value for full rights.
List Type
List Type is the type of list being referenced: User, Server or Rights.
USER_LIST - User list is the list type of interest.
SERVER_LIST - Server list is the list type of interest.
USER_RIGHTS_LIST - User rights list is the list type of interest.
AMWorks Software Matrix API User Guide
Structures
Some of the API calls use structures for input or output. The structures are defined in the
MatrixApi.h file and are repeated here.
User permissions
typedefstruct UserRight
{
UCHAR
ucSrvUID[8];
UCHAR
ucAccess;
UCHAR
ucMode;
}USER_RIGHT,*pUSER_RIGHT;
Legend
ucSrvUID - UID of the target device to assign rights to. An array of eight unsigned chars.
ucAccess - An unsigned char that can be one of the rights listed in the Rights section.
ucMode - Always zero.
User details
typedef struct UserDetail
{
USHORT
usUserName[16];
}USER_DETAIL,*pUSER_DETAIL;
Legend
usUserName[16] - This is a 15 character (max) Unicode string + NULL (Little Endian Storage)
that contains the username.
Server details
typedef struct ServerDetail
{
USHORT
usSrvName[16];
UCHAR
ucSrvUID[8];
}SERVER_DETAIL,*pSERVER_DETAIL;
3
4
AMWorks Software Matrix API User Guide
Legend
usSrvName[16] - This is a 15 character (max) Unicode string + NULL (Little Endian Storage) that
contains the name of the target device that is being returned.
ucSrvUID[8] - UID of the target device that is being returned. It is an array of eight unsigned chars.
Calls
NOTE: Except where noted, the API application must be logged into the AMWorks software for a call to
be received.
LoginAdministrator
Because the DLL is used by a matrix system Administrator, system login is required. The IP
address of the AMWorks software, valid system Administrator's password and idle time-out value
are required. For security reasons, the password sent over the network will be encrypted.
The rules for login are as follows:
•
Only one API is allowed to be logged in at a time.
•
All communication with the matrix system will fail without valid login.
•
The password must be the valid Administrator's password to the AMWorks software.
•
Login is rejected if the AMWorks software is in commissioning mode.
•
Login is rejected if another API, from a different machine, is already logged in.
•
Login is accepted if another API, running on the same machine, is already logged in. Since
only one API is allowed access to the matrix system, the previous API will automatically be
logged out.
Prototype
BOOL LoginAdministrator (PUCHAR pucIP, PUSHORT pusPassword, ULONG ulTimeout)
Return value
TRUE - Successful login to AMWorks software.
FALSE - Login attempt failed. Use the function GetLastMatrixError() to determine the reason
LoginAdministrator() attempt failed.
Parameters
PUCHAR pucIP - Pointer to a byte array that holds the IP address of the AMWorks software. Each
element of the byte array will contain a value between zero and 255.
Formatted as follows:
IP Address: nnn.xxx.yyy.zzz.
AMWorks Software Matrix API User Guide
5
Byte location:
pucIP[0] = nnn;
pucIP[1] = xxx;
pucIP[2] = yyy;
pucIP[3] = zzz;
// (0-255)
// (0-255)
// (0-255)
// (0-255)
PUSHORT pusPassword - Pointer to a zero terminated 15-character (max) Unicode string
containing the matrix system Administrator password. This is the Administrator's password to the
AMWorks software, not the "admin" password of the OSCAR® interface for the AMX switching
system. The password must be six to15 characters.
ULONG ulTimeout - Sets a time-out (in milli-seconds), which limits the idle time for logged in API
system sessions. The time-out value is reset by the AMWorks software after each call. The
AMWorks software will automatically logout the user if no activity is detected for this amount of
time. Setting the value to zero disables the time-out.
Remarks
This call initializes the Windows sockets DLL and is expecting at least Winsock2.2. This call sets
the IP address of the AMWorks software in the DLL and retrieves the AMWorks software version.
This MUST be the first call made by the external application.
Example
CString szPassword = _T("password");
ULONG ulTimeout
= 3000;
// Unicode String
// 3 seconds
// Set IP address to 172.26.12.75
UCHAR m_ucIP[4];
m_ucIP[0] = 0xac; // 172
m_ucIP[1] = 0x1a; // 26
m_ucIP[2] = 0x0c; // 12
m_ucIP[3] = 0x4b; // 75
//Get the pointer to the data buffer
PUSHORT password =
szPassword.GetBuffer(szPassword.GetBuffer(szPassword.GetLength()*sizeof(USHORT));
if (LoginAdministrator(m_ucIP, password, ulTimeout) == FALSE)
{
// Login attempt failed get last error code to determine reason.
DWORD eCode = MatrixGetLastError();
}
else
6
AMWorks Software Matrix API User Guide
{
// Login succeeded
}
LogoutAdministrator
LogoutAdmininstrator is used to end a login session. After a successful logout, the API application
will no longer accept calls. Once the time-out parameter has been set in the LoginAdministrator
function call, logout may be automatically executed by the AMWorks software if the timeout expires.
The AMWorks software also logs out a DLL user when the Administrator password is updated on
the AMWorks software. The API will forward calls to the AMWorks software if the time-out
expires, but the AMWorks software will fail the calls.
NOTE: The application, not the AMWorks software, is responsible for logout if the time-out value is set to zero.
Prototype
BOOL LogoutAdministrator()
Return Value
TRUE - Successful logout from the AMWorks software.
FALSE - Logout attempt failed. Use the function GetLastMatrixError() to determine the reason
the LogoutAdministrator() attempt failed.
Parameters
None required.
Remarks
This call logs out the Administrator from the matrix system and should be the last call made from
the API. This call also unloads the Windows socket DLL.
Example
If (LogoutAdministrator() == FALSE)
{
// Logout failed find out why.
DWORD eCode = MatrixGetLastError();
}
else
{
// Logged out successfully
}
AMWorks Software Matrix API User Guide
7
AddMatrixUser
AddMatrixUser is used to add a new user and password to the matrix system. The username and the
user password are required.
Prototype
BOOL AddMatrixUser(PUSHORT pusUserName, PUSHORT pusPassword)
Return Value
TRUE - Successfully added a new user to the matrix system.
FALSE - Add new user failed. Use the function GetLastMatrixError() to determine the reason
AddMatrixUser() failed.
Parameters
PUSHORT pusUserName - Pointer to a zero terminated 15 character (max) Unicode string
containing the username to be added to the matrix system.
PUSHORT pusPassword - Pointer to zero terminated 15 character (max) Unicode string that holds
the user’s password. Choose to either set a password of six to 15 characters or to set a blank
(zero character empty string) password. A blank password may not be set for the Administrator.
This function will automatically encrypt the password sent over the network.
Remarks
This call adds a new user to the matrix system.
Example
CString szUserName = _T("usertest");
//Unicode String
CString szPassword = _T("sunrise");
//Unicode String
PUSHORT username =
szUserName.GetBuffer(szUserName.GetLength()*sizeof(USHORT));
PUSHORT password =
szPassword.GetBuffer(szPassword.GetLength()*sizeof(USHORT));
if (AddMatrixUser(username, password) == FALSE)
{
// Add New User failed
DWORD eCode = MatrixGetLastError();
}
else
{
// New user successfully added
}
8
AMWorks Software Matrix API User Guide
DeleteMatrixUser
DeleteMatrixUser is used to delete a user from the matrix system. The username is required.
Prototype
BOOL DeleteMatrixUser(PUSHORT pusUserName)
Return Value
TRUE - Successfully deleted a user from the matrix system.
FALSE - Delete user failed. Use the function GetLastMatrixError() to determine the reason
DeleteMatrixUser() user failed.
Parameters
PUSHORT pusUserName - Pointer to a zero terminated 15 character (max) Unicode string
containing the username to be deleted from the matrix system.
Remarks
This call deletes a user from the matrix system.
Example
CString szUserName = _T("usertest"); //Unicode String
PUSHORT username =
szUserName.GetBuffer(szUserName.GetLength()*sizeof(USHORT));
if (DeleteMatrixUser(username) == FALSE)
{
// Delete User failed
DWORD eCode = MatrixGetLastError();
}
else
{
// User successfully deleted
}
UpdateMatrixUser
UpdateMatrixUser is used to update a username or password in the matrix system. The username
and password must be changed separately. If updating the username, both the old username and
AMWorks Software Matrix API User Guide
9
new username are required and the password argument must be NULL. If updating the password,
both the old username and the new password are required and the new username must be NULL.
Prototype
BOOL UpdateMatrixUser(PUSHORT pusOldName, PUSHORT pusNewName,
PUSHORT pusPassword)
Return Value
TRUE - Successfully updated user to the matrix system.
FALSE - Modified user failed. Use the function GetLastMatrixError() to determine the reason
UpdateMatrixUser() failed.
Parameters
PUSHORT pusOldName - Pointer to a zero terminated 15 character (max) Unicode string
containing the current user's name.
PUSHORT pusNewName - If changing the username, this is a pointer to a zero terminated 15
character (max) Unicode string containing the new username. If changing the password only, this is
not required and must be NULL.
PUSHORT pusPassword - If changing the username, this must be NULL. If changing the
password, this is a pointer to a zero terminated 15 character (max) Unicode string that holds the
users password. Choose to either set a password of six to 15 characters or to set a blank (zero
character) password. A blank password may not be set for the Administrator. This function will
automatically encrypt the password sent over the network.
Table 1: Parameters for the UpdateMatrixUser Call
pusOldName
psNewName
pusPassword
Comment
Username1
Username2
N/A
Username1 renamed to Username2.
Username1
N/A
xxxxxx
Username1 password changed to xxxxxx.
N/A
Username2
xxxxxx
Invalid argument. pusOldName must
be present and pusNewName must not
be present.
Username1
N/A
N/A
Invalid argument. Either pusNewName
pusPassword must be present.
Remarks
This call updates a username or password in the matrix system.
10
AMWorks Software Matrix API User Guide
Example
CString szOldName = _T("olduser"); //Unicode String
CString szNewName = _T("newuser"); //Unicode String
CString szPassword = _T("sunrise"); //Unicode String
PUSHORT oldname = szOldName.GetBuffer(szOldName.GetLength()*sizeof(USHORT));
PUSHORT newname =
szNewName.GetBuffer(szNewName.GetLength()*sizeof(USHORT));
PUSHORT password =
szPassword.GetBuffer(szPassword.GetLength()*sizeof(USHORT));
if (UpdateMatrixUser(oldname, newname, NULL) == FALSE)
{
// Modify User failed
DWORD eCode = MatrixGetLastError();
}
else
{
// User successfully modified
}
AssignMatrixUserPermissions
AssignMatrixUserPermissions is used to assign user rights (permissions) in the matrix system.
Prototype
BOOL AssignMatrixUserPermissions(PUSHORT pusUserName, pUSER_RIGHT pUserRights, int
nPermissionCnt)
Return Value
TRUE - Successfully updated user permissions to the matrix system.
FALSE - Assign user permissions failed. Use the function GetLastMatrixError() to determine the
reason AssignMatrixUserPermissions() failed.
Parameters
PUSHORT pusUserName - Pointer to a zero terminated 15 character (max) Unicode string
containing the username whose permissions are to be modified in the matrix system.
pUSER_RIGHT pUserRights - Pointer to a packed list of USER_RIGHT permission structures.
See MatrixApi.h for the structure declarations/definitions.
AMWorks Software Matrix API User Guide
int nPermissionCnt - Number of USER_RIGHT structures present in pUserRights list. Must be
greater than zero.
Remarks
This call assigns user permissions to target devices in the matrix system. More than one set of
permissions can be assigned per call.
Example
CString szUserName = _T("username"); //Unicode String
PUSHORT username =
szUserName.GetBuffer(szUserName.GetLength()*sizeof(USHORT));
// Set server IDs
UCHAR serverID1[8] = {0x01,0x0a,0x0d,0x00,0x01,0x90,0x10,0x10};
UCHAR serverID2[8] = {0x01,0x0a,0x0d,0x00,0x01,0x91,0x10,0x10};
USER_RIGHT rights1;
memcpy(rights1.ucSrvUID, serverID1, 8);
rights1.ucAccess = USER_RIGHTS_VIEW;
rights1.ucMode = 0;
USER_RIGHT rights2;
memcpy(rights2.ucSrvUID, serverID2, 8);
rights2.ucAccess = USER_RIGHTS_FULL;
rights2.ucMode = 0;
int nCnt = 2;
int nSize = sizeof(USER_RIGHT) * nCnt;
PUCHAR pRights = new(UCHAR[nSize]);
PUCHAR pTmpPtr = pRights;
// Merge all user rights
memcpy((pUSER_RIGHT)pTmpPtr, &rights1, sizeof(USER_RIGHT));
pTmpPtr += sizeof(USER_RIGHT);
memcpy((pUSER_RIGHT)pTmpPtr, &rights2, sizeof(USER_RIGHT));
if (AssignMatrixUserPermissions(username, (pUSER_RIGHT)pRights, nCnt) == FALSE)
{
// Assign permissions failed
DWORD eCode = MatrixGetLastError();
11
12
AMWorks Software Matrix API User Guide
}
else
{
// Assign user permissions successful
}
ClearMatrixUserRights
ClearMatrixUserRights clears all the permissions associated with a specific user in the
matrix system.
Prototype
BOOL ClearMatrixUserRights(PUSHORT pusUserName)
Return Value
TRUE - Successfully cleared user permissions to the matrix system.
FALSE - Clear user permissions failed. Use the function GetLastMatrixError() to determine the
reason ClearMatrixUserRights() failed.
Parameters
PUSHORT pusUserName - Pointer to a zero terminated 15 character (max) Unicode string
containing the username whose permissions are to be cleared on the matrix system.
Remarks
This call clears user permissions to target devices on the matrix system.
Example
CString szUserName = _T("username"); //Unicode String
PUSHORT username =
szUserName.GetBuffer(szUserName.GetLength()*sizeof(USHORT));
if (ClearMatrixUserRights(username) == FALSE)
{
// Clear user rights permissions failed
DWORD eCode = MatrixGetLastError();
}
else
{
// Successful
}
AMWorks Software Matrix API User Guide
13
GetMatrixUserList
GetMatrixUserList requests the list of users in the matrix system. User passwords are not included
within the list.
Prototype
INT GetMatrixUserList ()
Return Value
0 - Empty list retrieved from the AMWorks software.
n - Number of users in the list.
-1 - Get user list failed. Use the function GetLastMatrixError() to determine the reason
GetMatrixUserList() failed.
Parameters
None.
Remarks
This call retrieves all the users for the matrix system.
Example
int nUserCnt = GetMatrixUserList();
if (nUserCnt == 0)
{
// Empty User List
}
else if (nUserCnt > 0)
{
pUSER_DETAIL pUDPtr = NULL;
PVOID ptr = GetMatrixListHead(USER_LIST);
while ( (pUDPtr = (pUSER_DETAIL)GetMatrixListNext(USER_LIST, &ptr)) != NULL)
{
wprintf (_T("User - %s"), pUDPtr->usUserName);
}
}
else
{
14
AMWorks Software Matrix API User Guide
// Error
DWORD eCode = MatrixGetLastError();
}
GetMatrixServerList
GetMatrixServerList requests the list of servers in the matrix system.
Prototype
INT GetMatrixServerList ()
Return Value
0 - Empty list retrieved from the AMWorks software.
n - Number of target devices in the list.
-1 - Get server list failed. Use the function GetLastMatrixError() to determine the reason
GetMatrixServerList() failed.
Parameters
None.
Remarks
This call retrieves all the target devices in the matrix system.
Example
int nServerCnt = GetMatrixServerList();
if (nServerCnt == 0)
{
// Empty Server List
}
else if (nServerCnt > 0)
{
pSERVER_DETAIL pSDPtr = NULL;
PVOID ptr = GetMatrixListHead(SERVER_LIST);
UCHAR ucTmp[9];
while ( (pSDPtr = (pSERVER_DETAIL)GetMatrixListNext(SERVER_LIST, &ptr)) !=
NULL)
{
memset(ucTmp, 0, 9);
AMWorks Software Matrix API User Guide
15
memcpy(ucTmp, pSDPtr->ucSrvUID, 8);
wprintf (_T("Server Name - %s UID - %02x%02x%02x%02x%02x%02x%02x%02x"),
pSDPtr->usSrvName, ucTmp[0], ucTmp[1],ucTmp[2],ucTmp[3],ucTmp[4],
ucTmp[5],ucTmp[6],ucTmp[7]);
}
}
else
{
// Error
DWORD eCode = MatrixGetLastError();
}
GetMatrixUserRights
GetMatrixUserRights requests the rights for a specific user in the matrix system.
Prototype
INT GetMatrixUserRights (PUSHORT pusUserName)
Return Value
0 - Empty list retrieved from the AMWorks software.
n - Number of rights for the user.
-1 - Get user rights failed. Use the function GetLastMatrixError() to determine the reason
GetMatrixUserRights() failed.
Parameters
PUSHORT pusUserName - Pointer to a zero terminated 15 character (max) Unicode string
containing the username whose permissions are to be retrieved from the matrix system.
Remarks
This call retrieves all the rights for a specific user on the matrix system.
Example
CString szUsername = _T("username"); //Unicode String
pUSER_RIGHT pURPtr = NULL;
UCHAR ucTmp[8];
int rights =
GetMatrixUserRights(szUsername.GetBuffer(szUsername.GetLength()*sizeof(USHORT)))
;
16
AMWorks Software Matrix API User Guide
if( rights > 0 )
{
PVOID ptr = GetMatrixListHead(USER_RIGHTS_LIST);
while ( (pURPtr = (pUSER_RIGHT)GetMatrixListNext(USER_RIGHTS_LIST, &ptr)) !=
NULL)
{
memset(ucTmp,0,8);
CString szAccess;
memcpy(ucTmp,pURPtr->ucSrvUID,8);
switch(pURPtr->ucAccess)
{
case USER_RIGHTS_NONE:
szAccess = _T("NONE");
break;
case USER_RIGHTS_VIEW:
szAccess = _T("VIEW ONLY");
break;
case USER_RIGHTS_FULL:
szAccess = _T("FULL");
break;
}
wprintf (_T("Server UID - %02x%02x%02x%02x%02x%02x%02x%02x, Access %s"), ucTmp[0],
ucTmp[1],ucTmp[2],ucTmp[3],ucTmp[4],ucTmp[5],ucTmp[6],ucTmp[7],szAccess);
}
}
else if (rights == 0)
{
// Empty list
}
else
{
// Error
}
AMWorks Software Matrix API User Guide
17
GetMatrixListHead
GetMatrixListHead returns the head of the linked list requested. Use this function after calling
GetMatrixUserRights(), GetMatrixUserList(), or GetMatrixServerList() to process the list
requested from the matrix system.
Prototype
PVOID GetMatrixListHead(int nListType)
Return Value
PVOID - Pointer to the head of the requested list. To be used in GetMatrixListNext().
NULL - Returned if the requested list does not exist.
Parameters
int ListType - Type of list requested.
USER_LIST - Returns user list head.
SERVER_LIST - Returns server list head.
USER_RIGHTS_LIST - Returns user rights list head.
Examples
See examples in sections GetMatrixUserList beginning on page 13, GetMatrixServerList beginning
on page 14, and GetMatrixUserRights beginning on page 15.
GetMatrixListNext
GetMatrixListNext returns the element of the linked list requested by the pointer position. Use this
call to update the pointer position and process the linked lists retrieved from the matrix
system manager.
Prototype
PVOID GetMatrixListNext(INT nListType, PVOID* ptrPOSITION)
Return Value
PVOID - Pointer to the requested linked list node.
NULL - No more nodes in list.
Parameters
PVOID* ptrPOSITION - Pointer to position pointer for the list node. Should be head position (see
GetMatrixListHead beginning on page 17) when starting iteration.
18
AMWorks Software Matrix API User Guide
int ListType - Type of list requested.
USER_LIST - Returns user list head.
SERVER_LIST - Returns server list head.
USER_RIGHTS_LIST - Returns user rights list head.
Examples
See examples in sections GetMatrixUserList beginning on page 13, GetMatrixServerList beginning
on page 14, and GetMatrixUserRights beginning on page 15.
MatrixGetLastError
MatrixGetLastError returns the error code of the last operation. See MatrixApi.h file for
more information.
Prototype
DWORD MatrixGetLastError()
Return Value
See the following tables for possible error codes and descriptions.
Table 2: Error Codes for All Calls
All Calls
Comment
DLL_NOT_INITIALIZED
The DLL is not initialized. This error normally occurs
during login().
GENERAL_PACKET_ERROR
A communications error has occurred.
GENERAL_FAULT_ERROR
A matrix system error has occurred.
Table 3: Error Codes for LoginAdministrator
LoginAdministrator
Comment
ADMIN_LOGIN_OK
The Administrator logged in successfully.
ADMIN_LOGIN_FAIL_PASSWORD
An invalid Administrator password was reported by
matrix system.
ADMIN_LOGIN_FAIL_ARGUMENT
Invalid argument. This usually results from an invalid buffer
or password length.
AMWorks Software Matrix API User Guide
19
Table 3: Error Codes for LoginAdministrator
LoginAdministrator
Comment
ADMIN_LOGIN_FAIL_BUSY
The AMWorks software is in commissioning mode.
ADMIN_LOGIN_FAIL_IN_USE
Another DLL is already logged in.
DLL_INITIALIZATION_FAILED
A failure occurred while initializing the DLL.
INVALID_MGR_VERSION
The AMWorks software is an early version that does not
support API.
Table 4: Error Codes for LogoutAdministrator
LogoutAdministrator
Comment
ADMIN_LOGOUT_OK
The Administrator logged out successfully.
ADMIN_LOGOUT_FAIL_NOT_LOGGED_IN
The API was not logged in at the time of the call.
ADMIN_LOGOUT_FAIL_NAME
Invalid request. The call attempted to logout a normal (nonadministrator) user instead of the Administrator.
Table 5: Error Codes for AddMatrixUser
AddMatrixUser
Comment
ADD_USER_OK
The user was successfully added.
ADD_USER_FAIL_ERROR
A general operations error occurred.
ADD_USER_FAIL_BUSY
The AMWorks software is in commissioning mode.
ADD_USER_FAIL_ACCESS
The API was not logged in at the time of the call.
ADD_USER_IN_USE
Another DLL is already logged in.
ADD_USER_FAIL_USER_EXISTS
The user already exists on the matrix system.
ADD_USER_FAIL_USER_NAME
An invalid username was reported by the matrix system.
ADD_USER_FAIL_ARGUMENT
Invalid argument. This usually results from an invalid
username or password length.
ADD_USER_FAIL_EXCEEDED_LIMIT
The call exceeded number of users that can be added to
the matrix system.
20
AMWorks Software Matrix API User Guide
Table 5: Error Codes for AddMatrixUser (Continued)
AddMatrixUser
Comment
ADD_USER_FAIL_ADMIN_INVALID
Invalid request. The call attempted to add an Administrator
instead of a normal user to matrix system.
ADD_USER_FAIL_OUT_OF_SYNC
The switching system and the AMWorks software are
not synchronized.
Table 6: Error Codes for DeleteMatrixUser
DeleteMatrixUser
Comment
DELETE_USER_OK
The user was successfully deleted.
DELETE_USER_FAIL_ERROR
A general operations error occurred.
DELETE_USER_FAIL_BUSY
The AMWorks software is in commissioning mode.
DELETE_USER_FAIL_ACCESS
The API was not logged in at the time of the call.
DELETE_USER_IN_USE
Another DLL is already logged in.
DELETE_USER_FAIL_INVALID_USER
The user doesn't exist on the matrix system.
DELETE_USER_FAIL_USER_NAME
An invalid username was reported by the matrix system.
DELETE_USER_FAIL_ARGUMENT
Invalid argument. This usually results from an invalid
username length.
DELETE_USER_FAIL_ADMIN_INVALID
Invalid request. The call attempted to delete an
Administrator instead of a normal user from the
matrix system.
DELETE_USER_FAIL_OUT_OF_SYNC
The switching system and the AMWorks software are
not synchronized.
Table 7: Error Codes for UpdateMatrixUser
UpdateMatrixUser
Comment
UPDATE_USER_OK
The user was successfully updated.
UPDATE_USER_FAIL_ERROR
A general operations error occurred.
UPDATE_USER_FAIL_BUSY
The AMWorks software is in commissioning mode.
UPDATE_USER_FAIL_ACCESS
The API was not logged in at the time of the call.
AMWorks Software Matrix API User Guide
21
Table 7: Error Codes for UpdateMatrixUser (Continued)
UpdateMatrixUser
Comment
UPDATE_USER_IN_USE
Another DLL is already logged in.
UPDATE_USER_FAIL_INVALID_USER
The user doesn't exist on the matrix system.
UPDATE_USER_FAIL_USER_NAME
An invalid username was report by matrix system.
UPDATE_USER_FAIL_ARGUMENT
Invalid argument. This usually results from an invalid
username or password length.
UPDATE_USER_FAIL_USER_EXISTS
The user (new username) already exists.
UPDATE_USER_FAIL_ADMIN_INVALID
Invalid request. The call attempted to update the
Administrator instead of a normal user.
UPDATE_USER_FAIL_OUT_OF_SYNC
The switching system and the AMWorks software are
not synchronized.
Table 8: Error Codes for AssignMatrixUserPermissions
AssignMatrixUserPermissions
Comment
RIGHTS_ASSIGNED_OK
The user rights were successfully updated.
RIGHTS_ASSIGNED_FAIL_ERROR
A general operations error occurred.
RIGHTS_ASSIGNED_FAIL_BUSY
The AMWorks software is in commissioning mode.
RIGHTS_ASSIGNED_FAIL_ACCESS
The API was not logged in at the time of the call.
RIGHTS_ASSIGNED_IN_USE
Another DLL is already logged in.
RIGHTS_ASSIGNED_INVALID_USER
The user doesn't exist on the matrix system.
RIGHTS_ASSIGNED_INVALID_SERVER_UID
The target device UID format is invalid.
RIGHTS_ASSIGNED_INVALID_SERVER
The target device doesn't exist.
RIGHTS_ASSIGNED_LIMIT_EXCEEDED
The target device system limits are exceeded.
RIGHTS_ASSIGNED_INVALID_ARGUMENT
Invalid argument. This usually results from an invalid
username or password length.
RIGHTS_ASSIGNED_FAIL_USER_NAME
An invalid username was reported by the matrix system.
RIGHTS_ASSIGNED_FAIL_ADMIN_INVALID
Invalid request. The call attempted to assign permissions to
the Administrator instead of a normal user.
RIGHTS_ASSIGNED_FAIL_OUT_OF_SYNC
The switching system and the AMWorks software are
not synchronized.
22
AMWorks Software Matrix API User Guide
Table 9: Error Codes for GetServerList
GetServerList
Comment
SERVER_LIST_OK
The server list was successfully retrieved.
SERVER_LIST_FAIL_ERROR
A general operations error occurred.
SERVER_LIST_FAIL_BUSY
The AMWorks software is in commissioning mode.
SERVER_LIST_FAIL_ACCESS
The API was not logged in at the time of the call.
SERVER_LIST_IN_USE
Another DLL is already logged in.
Table 10: Error Codes for GetUserList
GetUserList
Comment
USER_LIST_OK
The user list was successfully retrieved.
USER_LIST_FAIL_ERROR
A general operations error occurred.
USER_LIST_FAIL_BUSY
The AMWorks software is in commissioning mode.
USER_LIST_FAIL_ACCESS
The API was not logged in at the time of the call.
USER_LIST_IN_USE
Another DLL is already logged in.
Table 11: Error Codes for GetUserRights
GetUserRights
Comment
USER_RIGHTS_OK
The user rights were successfully retrieved.
USER_RIGHTS_FAIL_ERROR
A general operations error occurred.
USER_RIGHTS_FAIL_BUSY
The AMWorks software is in commissioning mode.
USER_RIGHTS_FAIL_ACCESS
The API was not logged in at the time of the call.
USER_RIGHTS_IN_USE
Another DLL is already logged in.
USER_RIGHTS_FAIL_INVALID_USER
The user doesn't exist on the matrix system.
USER_RIGHTS_FAIL_USER_NAME
An invalid username was reported by the matrix system.
AMWorks Software Matrix API User Guide
Table 11: Error Codes for GetUserRights (Continued)
GetUserRights
Comment
USER_RIGHTS_FAIL_ARGUMENT
Invalid argument. This usually results from an
invalid username.
USER_RIGHTS_FAIL_ADMIN_INVALID
Invalid request. The call attempted to get rights for the
Administrator instead of a normal user.
Table 12: Error Codes for ClearUserRights
ClearUserRights
Comment
CLEAR_RIGHTS_OK
Successfully cleared user rights.
CLEAR_RIGHTS_FAIL_ERROR
A general operations error occurred.
CLEAR_RIGHTS_FAIL_BUSY
The AMWorks software is in commissioning mode.
CLEAR_RIGHTS_FAIL_ACCESS
The API was not logged in at the time of the call.
CLEAR_RIGHTS_IN_USE
Another DLL is already logged in.
CLEAR_RIGHTS_FAIL_INVALID_USER
The user doesn't exist on the matrix system.
CLEAR_RIGHTS_FAIL_USER_NAME
An invalid username was reported by the matrix system.
CLEAR_RIGHTS_FAIL_ARGUMENT
Invalid argument. This usually results from an
invalid username.
USER_RIGHTS_FAIL_ADMIN_INVALID
Invalid request. The call attempted to clear rights for the
Administrator instead of a normal user.
CLEAR_RIGHTS_FAIL_OUT_OF_SYNC
The switching system and the AMWorks software are
not synchronized.
Table 13: Error Codes for GetMgrVersion
GetMgrVersion
Comment
GET_MANAGER_OK
The version was successfully retrieved.
GET_MANAGER_FAIL_ACCESS
The API was not logged in at the time of the call.
GET_VERSION_FAIL_ARGUMENT
Invalid argument.
23
24
AMWorks Software Matrix API User Guide
Table 14: Error Codes for GetApiVersion
GetApiVersion
Comment
GET_API_OK
The version was successfully retrieved.
GET_VERSION_FAIL_ARGUMENT
Invalid argument.
Parameters
None.
Examples
See call examples above.
GetMgrVersion
GetMgrVersion retrieves the AMWorks software version that was returned during
LoginAdministrator() function call.
Prototype
BOOL GetMgrVersion(PUSHORT pusVersion, PUINT punSize)
Return Value
TRUE - Successfully retrieved AMWorks software version.
FALSE - Failed, most likely because the buffer is too small.
Parameters
PUSHORT pusVersion - Pointer to a buffer to receive the Unicode version string. Version string
may be variable in length and is in the form:
Major.Minor.Release.Build
5.2.0.39
This would require a wide buffer of at least nine characters (18 bytes).
PUINT punSize - Pointer to variable that contains the size (in Unicode characters) of the buffer
passed in. If buffer is not large enough, the size required is filled in and the call failed.
Example
#define VERSION_LEN 20 //version should always be less than 20 chars
USHORT chVersion[VERSION_LEN] = {0};
UINT unSize = VERSION_LEN;
AMWorks Software Matrix API User Guide
25
//get version
GetMgrVersion(chVersion,&unSize);
GetApiVersion
GetApiVersion retrieves the DLL's version.
NOTE: This is the only call that will succeed if the API is not logged into the AMWorks software.
Prototype
BOOL GetApiVersion(PUSHORT pusVersion, PUINT punSize)
Return Value
TRUE - Successfully retrieved DLL's version.
FALSE - Failed, most likely because the buffer is too small.
Parameters
PUSHORT pusVersion - Pointer to a buffer to receive the Unicode version string. Version string
may be variable in length and is in the form:
Major.Minor.Release.Build
e5.2.0.39
This would require a wide buffer of at least nine characters (18 bytes).
PUINT punSize - Pointer to variable that contains the size (in Unicode characters) of the buffer
passed in. If buffer is not large enough, the size required is filled in and the call failed.
Example
#define VERSION_LEN 20 //version should always be less than 20 chars
USHORT chVersion[VERSION_LEN] = {0};
UINT unSize = VERSION_LEN;
//get version
GetApiVersion(chVersion,&unSize);