Black Box ACR1000A-CTL API User Manual

Size:
1.89 Mb
Download

ACR1000A-CTLAPI

ServSwitchiPATH Manager API

Application Programming Interface (API) Manual

Customer

Support

Information

Order toll-freein the U.S.: Call877-877-BBOX(outside U.S. call724-746-5500)

FREE technical support 24 hours a day, 7 days a week: Call 724-746-5500or fax724-746-0746Mailing address: Black Box Corporation, 1000 Park Drive, Lawrence, PA15055-1018

Web site: www.blackbox.com • E-mail:info@blackbox.com

ServSwitch iPATH Manager API Documentation

Table of Contents

 

Methods

 

login ...............................................................................................................................................................................

3

logout ...............................................................................................................................................................................

4

get_devices............................................................................................................................................................................

5

get_channels..........................................................................................................................................................................

8

get_presets............................................................................................................................................................................

9

connect_channel..................................................................................................................................................................

11

connect_preset....................................................................................................................................................................

12

disconnect_channel.............................................................................................................................................................

13

disconnect_preset................................................................................................................................................................

13

We‘re here to help! If you have any questions about your application or our products, contact Black Box Tech Support at 724-746-5500or go to blackbox.com and click on “Talk to Black Box.”

You’ll be live with one of our technical experts in less than 30 seconds.

Page 2

724-746-5500| blackbox.com

ServSwitch iPATH Manager API Documentation

API Documentation

API version: 2

Changelog

v2 (IPATH v2.3) - added get_devices, get_channels, connect_channel, disconnect_channel. Updated version compatibility information.

v1 (IPATH v1.3) - added login, logout, get_presets, connect_preset, disconnect_preset

Methods login logout get_devices

get_channels get_presets connect_channel connect_preset disconnect_channel disconnect_preset

login

This method was last updated in API version 1, and is compatible with API requests from version 1 onwards.

The API will require a valid IPATH user's login credentials to be presented in the first request. The API will return an authentication code, which must be passed in all future requests. This authentication code can be re-useduntil a logout request is made, at which point the authentication code will no longer be valid.

The concept of an “anonymous user” can apply to the API. If no login username and password are provided, the API will return an authentication token for the anonymous user (either the same one as for the OSD, or else an “anonymous API user” account can be created).

Input parameters:

-username

-password

-v (the IPATH API version this request is designed for)

Output values:

-timestamp - the current server time

-version - the current API version number

-token - an authentication code for future API requests

-success

NOTE: login examples are on the next page.

724-746-5500| blackbox.com

Page 3

ServSwitch iPATH Manager API Documentation

Examples

Input:

/api/?v=1&method=login&username=xxxxx&password=xxxxx

Output: <api_response>

<version>1</version>

<timestamp>2012-12-1412:12:12</timestamp> <success>1</success> <token>5cf494a71c29e9465a57a81e0a2d602c</token>

</api_response> or <api_response>

<version>1</version>

<timestamp>2012-12-1412:12:12</timestamp> <success>0</success>

<errors>

<error>

<code>2</code>

<msg>Invalid username or password</msg>

</error>

</errors> </api_response>

logout

This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.

The authentication token provided by the login function can be used until the logout function is called.

Input parameters:

-token

-v (the IPATH API version this request is designed for)

Output values:

-timestamp - the current server time

-success - 0 = fail, 1 = success

Examples

Input:

/api/?method=logout&token=xxxxx&v=1

Output: <api_response>

<version>1</version> <timestamp>2011-02-0415:24:15</time> <success>1</success>

s</api_response>

Page 4

724-746-5500| blackbox.com

ServSwitch iPATH Manager API Documentation

or

<api_response> <version>1</version>

<timestamp>2012-12-1212:12:12</timestamp> <success>0</success>

<errors>

<error>

<code>3</code>

<msg>Error logging out (you may already have logged out)</msg>

</error>

</errors> </api_response>

get_devices

This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.

This function returns a list of devices.

Input parameters:

-token

-v (the IPATH API version this request is designed for)

-device_type ('rx' = receivers, 'tx' = transmitters. Default = 'rx')

-filter_d_name (Optional. Device name search string)

-filter_d_description (Optional. Device description search string)

-filter_d_location (Optional. Device location search string)

-sort (Optional. Sort results by 'name'/'description'/'location'. Default = 'name')

-sort_dir (Optional. Sort direction for results 'asc'/'desc'. Default = 'asc')

-status (Optional. '','outdated_iPATH_ip','rebooting','offline','outdated_firmware','invalid_backup_firmware','rebooting','upgrading'

-show_all (Optional. If set and not blank, shows all receivers, not just those the logged-inuser is permitted to use)

-page (page number to start showing results for, default = 1)

-results_per_page (number of results per page, default = 1000)

Output values:

-version - the current API version number

-timestamp - the current server time

-success

-page (page number)

-results_per_page (number of results per page, default = unlimited)

-total_devices - the total number of devices

-count_devices - the number of devices on this page

-for each device:

-attribute: item (e.g. 17th device)

-d_id (device id)

-d_mac_address (device MAC address)

-d_name (device name)

-d_description (device description)

-d_location (device location)

-d_online (0 = offline, 1 = online, 2 = rebooting, 3 = factory_resetting, 4 = firmware_upgrading, 6 = running backup firmware)

-d_type (rx, tx)

724-746-5500| blackbox.com

Page 5

ServSwitch iPATH Manager API Documentation

-d_version (1 = ACR1000A, 2 = ACR1002A)

-d_variant ('', 'b' = ACR1002A)

-d_ip_address

-d_configured (0 = no, 1 = yes)

-d_valid_firmware (0 = no, 1 = yes)

-d_valid_backup_firmware (0 = no, 1 = yes)

-d_firmware (firmware version, e.g. 2.5.17879)

-d_backup_firmware (backup firmware version)

-d_date_added (Date device added to iPATH network e.g. 2012-07-1322:17:22) The following property is only returned for transmitters:

-count_transmitter_channels (the number of channels containing this transmitter) The following properties are only returned for receivers:

-con_start_time (start time of last connection e.g. 2012-09-0713:33:17)

-con_end_time (empty if connection still active, else date/time the connection was ended e.g. 2012-09-0713:33:17)

-con_exclusive (0/1 - if the last connection is/was in exclusive mode)

-con_control (0/1 - if the last connection has/had USB enabled)

-u_username (username of the user who initiated the last connection)

-u_id (user ID of the user who initiated the last connection)

-c_name (name of the channel last connected)

-count_receiver_groups (the number of receiver groups this receiver is a part of)

-count_users (the number of users who have access to this receiver)

Examples

Input: /api/?v=2&method=get_devices&token=xxxxx

/api/?v=2&method=get_devices&device_type=tx&page=2&results_per_page=3&token=xxxxx

Output: <api_response>

<version>2</version>

<timestamp>2012-09-1214:56:11</timestamp> <success>1</success>

<page>2</page> <results_per_page>3</results_per_page> <total_devices>12</total_devices> <count_devices>3</count_devices> <devices>

<device item="4"> <d_id>170</d_id>

<d_mac_address>00:0F:58:01:6E:3D</d_mac_address> <d_name>RX 123</d_name>

<d_online>1</d_online> <d_type>rx</d_type> <d_version>2</d_version> <d_variant></d_variant> <d_ip_address>10.10.10.66</d_ip_address> <d_description></d_description> <d_location>Server Rack 3</d_location> <d_configured>1</d_configured> <d_valid_firmware>1</d_valid_firmware>

Page 6

724-746-5500| blackbox.com

ServSwitch iPATH Manager API Documentation

<d_valid_backup_firmware>1</d_valid_backup_firmware> <d_firmware>2.3.16682</d_firmware> <d_backup_firmware>2.3.16682</d_backup_firmware> <d_date_added>2012-07-1401:37:07</d_date_added> <con_exclusive>0</con_exclusive> <con_control>1</con_control><con_start_time>2012-09-0713:33:19</con_start_time> <con_end_time/>

<u_username>admin</u_username> <u_id>1</u_id>

<c_name>Channel 1</c_name> <count_receiver_groups>1</count_receiver_groups> <count_users>1</count_users> <custom_settings>0</custom_settings>

</device>

</devices> </api_response>

<api_response> <version>2</version>

<timestamp>2012-09-1214:56:11</timestamp> <success>1</success>

<page>1</page> <results_per_page>1</results_per_page> <total_devices>1</total_devices> <count_devices>1</count_devices> <devices>

<device item="1"> <d_id>64</d_id>

<d_mac_address>00:0F:58:01:56:85</d_mac_address> <d_name>TX 456</d_name>

<d_online>0</d_online> <d_type>tx</d_type> <d_version>1</d_version> <d_variant></d_variant> <d_ip_address>1.1.201.31</d_ip_address> <d_description></d_description> <d_location></d_location> <d_configured>1</d_configured> <d_valid_firmware>1</d_valid_firmware>

<d_valid_backup_firmware>1</d_valid_backup_firmware> <d_firmware>2.1.15747</d_firmware> <d_backup_firmware>2.1.15747</d_backup_firmware> <d_date_added>2012-07-1317:50:04</d_date_added> <count_transmitter_channels>3</count_transmitter_channels> <custom_settings>0

</custom_settings> </device>

</devices> </api_response>

724-746-5500| blackbox.com

Page 7

ServSwitch iPATH Manager API Documentation

get_channels

This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.

This simple function returns a list of channels available to the authenticated user, for a specific receiver. Input parameters:

-token

-v (the iPATH API version this request is designed for)

-page (page number to start showing results for, default = 1)

-results_per_page (number of results per page, default = 1000)

-device_id (ID of the receiver that this channel will be connected to. Recommended to ensure full checks for connection mode availability.

-filter_c_name (channel name search string)

-filter_c_description (channel description search string)

-filter_c_location (channel location search string)

-filter_favorites (set this non-emptyto only show a user's favorites)

Output values:

-version - the current API version number

-timestamp - the current server time

-success

-page (page number)

-results_per_page (number of results per page, default = unlimited)

-count_channels - the number of channels on this page, available to the authenticated user

-for each channel:

-attribute: item (e.g. 17th channel)

-c_id (channel id)

-c_name (channel name)

-c_description (channel description)

-c_location (channel location)

-c_favorite (true if this channel is in the user's favorites, 0-9if it's a numbered shortcut)

-view_button (disabled/enabled/hidden - whether the user can connect to the preset in view-onlymode. disabled = no, because something is in use by someone else. hidden = never. enabled = yes.

If the device_id of the proposed receiver to be used in the connection is not provided, this will not necessarily be an accurate indication of whether other connections may actually interfere)

-shared_button (disabled/enabled/hidden - as above, but in shared mode)

-exclusive_button (disabled/enabled/hidden - as above, but in exclusive mode)

Examples

Input: /api/?v=2&method=get_channels&token=xxxxx

Output: <api_response>

<version>2</version>

<timestamp>2012-12-1412:12:12</timestamp> <success>1</success>

<page>1</page> <results_per_page>10</results_per_page>

Page 8

724-746-5500| blackbox.com

ServSwitch iPATH Manager API Documentation

<count_channels>2</count_channels> <channel item="1">

<c_id>3</c_id> <c_name>Channel 1</c_name>

<c_description>Description for Channel 1</c_description> <c_location>Location of Channel 1</c_location> <c_favorite>false</c_favorite> <view_button>disabled</view_button> <shared_button>disabled</shared_button> <exclusive_button>disabled</exclusive_button>

</channel> <channel item="2">

<c_id>5</c_id> <c_name>Channel 2</c_name>

<c_description>Description for Channel 2</c_description> <c_location>Location of Channel 2</c_location> <c_favorite>2</c_favorite> <view_button>disabled</view_button> <shared_button>enabled</shared_button> <exclusive_button>hidden</exclusive_button>

</channel> </api_response>

get_presets

This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.

This simple function returns a list of presets available to the authenticated user.

Input parameters:

-token

-v (the iPATH API version this request is designed for)

-results_per_page (number of results per page, default = 1000)

-page (page number to start showing results for, default = 1)

Output values:

-version - the current API version number

-timestamp - the current server time

-success

-page (page number)

-results_per_page (number of results per page, default = unlimited)

-total_presets - the total number of presets available to the authenticaed user

-count_presets - the number of presets on this page, available to the authenticated user

-for each connection_preset:

-attribute: item (e.g. 17th preset)

-cp_id (preset id)

-cp_name (preset name)

-cp_description (preset description)

-cp_pairs (the number of channel-receiverpairs in this preset)

-problem_cp_pairs (the number of channel-receiverpairs that are misconfigured (e.g. receiver offline, receiver not defined)

724-746-5500| blackbox.com

Page 9

ServSwitch iPATH Manager API Documentation

-count_active_cp (the number of channel-receiverpairs in this preset that are already connected)

-connected_rx_count (the number of receivers in this preset that are already connected)

-view_button (disabled/enabled/hidden - whether the user can connect to the preset in view-onlymode. disabled = no, because something is in use by someone else. hidden = never. enabled = yes)

-shared_button (disabled/enabled/hidden - as above, but in shared mode)

-exclusive_button (disabled/enabled/hidden - as above, but in exclusive mode)

Examples

Input: /api/?v=1&method=get_presets&token=xxxxx

Output: <api_response>

<version>1</version>

<timestamp>2012-12-1412:12:12</timestamp> <success>1</success>

<page>1</page> <results_per_page>10</results_per_page> <total_presets>2</total_presets> <count_presets>2</count_presets> <connection_preset item="1">

<cp_id>3</cp_id> <cp_name>Preset 1</cp_name>

<cp_description>Description for Preset 1</cp_description> <cp_pairs>1</cp_pairs>

<problem_cp_pairs/> <count_active_cp/>

<connected_rx_count>1</connected_rx_count> <view_button>disabled</view_button> <shared_button>disabled</shared_button> <exclusive_button>disabled</exclusive_button>

</connection_preset> <connection_preset item="2">

<cp_id>4</cp_id> <cp_name>Preset 2</cp_name>

<cp_description>Description for Preset 2</cp_description> <cp_pairs>2</cp_pairs>

<problem_cp_pairs/> <count_active_cp/> <connected_rx_count/> <view_button>enabled</view_button>

<shared_button>hidden</shared_button> <exclusive_button>hidden</exclusive_button>

</connection_preset> </api_response>

Page 10

724-746-5500| blackbox.com