{"id":1864,"date":"2019-11-07T14:33:16","date_gmt":"2019-11-07T22:33:16","guid":{"rendered":"https:\/\/portal.staylinked.com\/sl\/kb\/?post_type=ht_kb&#038;p=1864"},"modified":"2024-07-22T07:58:51","modified_gmt":"2024-07-22T14:58:51","slug":"host-application-programming-interface-api","status":"publish","type":"ht_kb","link":"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/","title":{"rendered":"StayLinked Application Programming Interface (API) Options"},"content":{"rendered":"\n<h2>API Types<\/h2>\n\n\n\n<p>APIs are available within StayLinked in three different types.<\/p>\n\n\n\n<ul><li>APIs are available within <a href=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/configuration-dialogues-for-screen-recognition\/#host-application-programming-interfaces-apis\">Screen Recognition<\/a>. This is the most common use and primary area for implementing APIs.<\/li><li>Starting in server version 15.3 there are <a href=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/telnet-host-administration2\/#manage-session-settings-menu-option\">session settings<\/a> that include API options at the Start, Reconnection (requires server v15.5), Global (entire session duration), and End of any session.<\/li><li>Lastly, there are screen-based APIs that required adjustments to a host application or script. <\/li><\/ul>\n\n\n\n<h2>Screen Recognition APIs<\/h2>\n\n\n\n<p>Screen Recognition offers an APIs tab within the recognition event. See the <a href=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/configuration-dialogues-for-screen-recognition\/#host-application-programming-interfaces-apis\">Screen Recognition section<\/a> for details about implementing these APIs within your user workflow based on screen contents from the emulation host.<\/p>\n\n\n\n<h2>Session Setting APIs<\/h2>\n\n\n\n<p>Start, Reconnect, and End APIs are limited use to the session state as defined in the name\/type. Global APIs are available at any time within the session, often launched on-demand by users by mapping a key code to one of the Global API options.<\/p>\n\n\n\n<p>Version 15.5 of the StayLinked Server increases the number of session APIs to 999, creates a new host input API, and includes the option for comma-separated APIs in the [*API XXX,XXX,XXX] mnemonic to perform multiple APIs in a single instruction.<\/p>\n\n\n\n<h2>Screen-Based Host APIs<\/h2>\n\n\n\n<p>This article contains general information about the screen-based APIs. Screen Recognition features can be used to implement most of these functions without adjustment of the host application design. Using StayLinked Screen Recognition does not detail each API, since the functions are identical, but the dialogues are described within the Screen Recognition articles. Some APIs are available only within Screen Recognition and no new text-based APIs are planned for addition in future releases.<\/p>\n\n\n\n<p>This article describes the StayLinked Host APIs. This Application Programming Interface that can be accessed from your own Host application is an exclusive feature of the StayLinked product. An overview is provided, along with instructions for adding these powerful functions to your end-user applications. Detailed descriptions for each Host API are available in the article for those descriptions.<\/p>\n\n\n\n<p><strong>A list of these APIs and their details can be found <a href=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api-2\/\">here<\/a>.<\/strong><\/p>\n\n\n\n<h3>Overview of StayLinked Host API<\/h3>\n\n\n\n<p>Another benefit of the host-based StayLinked\narchitecture is its ability to extend session control functions to your host\napplications. As simple as writing and reading display screens, these powerful\nAPIs provide the following power to your end-user applications:<\/p>\n\n\n\n<ul><li>Determine\nwhether the device is actually running a StayLinked session<\/li><li>Retrieve\nStayLinked session attributes like Device Type, IP Address, MAC Address, Device\nName, Client Version, Display Rows and Columns, etc.<\/li><li>Wirelessly\ntransfer files to and from the devices (great for uploading batch data)<\/li><li>Reboot,\nRestart, Disconnect and Terminate the session<\/li><li>Send\nspecial, highly-visible messages to the device<\/li><li>Send\nlong, short or double beeps to the device<\/li><li>Run\nremote commands and programs on the device<\/li><li>Control\nthe scanner on the device; enable and disable the laser and soft-trigger the\nscanner<\/li><li>Send\naudible beeps to the device or cause the device to vibrate, if supported<\/li><\/ul>\n\n\n\n<p> Control the Speech engine on the device for Text-to-Speech and Voice Recognition functions <\/p>\n\n\n\n<h3>Using the StayLinked Host Application Programming Interface<\/h3>\n\n\n\n<p>This section will explain the steps necessary to integrate this powerful interface into your end-user applications.<\/p>\n\n\n\n<h4>How the Host APIs Work<\/h4>\n\n\n\n<p>The StayLinked Host APIs are accessed using special display screens to communicate with the host-based StayLinked Server. Most application screens are forward directly to the client device for display, but the special Host API screens are intercepted by the StayLinked Server before they are forwarded to the device for display. If the server identifies a screen as a Host API function request, it will interpret the data on the screen and then perform the requested function. You can control whether the actual screen is forwarded to the device for display or not. Once the server has completed the processing of the API function, the server can respond by sending the mnemonic ([enter]) to the screen (like you pressing the Enter key), or you can specify an alternate screen response if desired.<\/p>\n\n\n\n<h4>How Host API screens are recognized by the StayLinked Server<\/h4>\n\n\n\n<p>Each time your host application writes text to\nthe screen, a \u2018presentation space event\u2019 will be transmitted to the Telnet\nClient inside the StayLinked Server. This \u2018presentation space event\u2019 will have\na starting position and an ending position within the telnet screen area. These\n\u2018presentation space events\u2019 are triggered by the host application writing text\nto the screen and the starting and ending positions of the event can be\npresented differently, depending upon the telnet server, the hardware platform\noperating system and type of terminal emulation. In any case, it is the\nstarting and ending positions that are used to determine if a Host API is to be\nprocessed or not.<\/p>\n\n\n\n<p>When a \u2018presentation space event\u2019 is transmitted from the Telnet Server to the Telnet Client inside the StayLinked Server, the event will be analyzed to determine if this event spans the Host API column and row. If this event does contain the Host API column and row, then the server will look for the \u2018API Identifier\u2019 at that column and row. If the API identifier is found, then this \u2018presentation space event\u2019 will be handled as a StayLinked Host API screen. Now, the server will parse the API arguments from the screen and perform the desired function as dictated by the API identifier and arguments. The StayLinked Server can be configured to send this specific \u2018presentation space event\u2019 to the device for display, but typically, the Host API screens are not sent to the device. It depends upon your specific implementation for displaying the Host API and whether your methodology requires the screen to be displayed on the device or not. <\/p>\n\n\n\n<p>You can configure these options to control how StayLinked Host APIs are recognized and processed. The default settings are: <\/p>\n\n\n\n<p><strong>Separator Character = 0x7E (~)<br> Host API Column = 2<br> Host API Row = 1<br> Show API Screens = false<\/strong><\/p>\n\n\n\n<h4>After a Host API screen is processed by the StayLinked Server<\/h4>\n\n\n\n<p>It can be important for your host application\nto know when the StayLinked Server has finished processing the API function\nthat you have requested. After the StayLinked Server recognizes and processes a\nHost API function, it will respond to your application by automatically\npressing the Enter key. This is the default behavior of the StayLinked Server,\nbut this response can be changed based upon the requirements of your\napplication. If you would rather have the StayLinked Server respond to a Host\nAPI using, for example the F1 key, then you can specify this \u2018optional\nresponse\u2019 by adding an additional argument to the specific Host API screen.<\/p>\n\n\n\n<p>Here is a Host API string for the \u2018Display Message\u2019 API with a default server response. In this example, the server will send the message to the device and then press Enter in the Telnet session.<\/p>\n\n\n\n<p><strong>~API04~Mr. Watson come here, I want to see you.~<\/strong><\/p>\n\n\n\n<p>Here is a Host API string for the \u2018Display Message\u2019 API with an optional server response of F1. In this example, the server will send the message to the device and then press F1 in the Telnet session.<\/p>\n\n\n\n<p><strong>~API04~Mr. Watson come here, I want to see you.~[pf1]~<\/strong><\/p>\n\n\n\n<p>The \u2018optional response\u2019 can be a script and can implement any mnemonic supported by StayLinked. Here is an example optional response that will type OK and send a carriage return.<\/p>\n\n\n\n<p><strong>~API04~Mr. Watson come here, I want to see you.~OK[hex 0D]~<\/strong><\/p>\n\n\n\n<p>If you want to prevent the StayLinked Server from providing any response at all, use the <strong>[null]<\/strong> mnemonic as the optional response. In this example, the server will send the message to the device and provide no response to the application.<\/p>\n\n\n\n<p><strong>~API04~Mr. Watson come here, I want to see you.~[null]~<\/strong><\/p>\n\n\n\n<p>There are some Host APIs that require a\nresponse from the server, so the following Host APIs do not support the\n\u2018optional response\u2019 feature.<\/p>\n\n\n\n<ul><li>API01 \u2013 Retrieve Session Properties<\/li><li>API02 \u2013 Send File to Device<\/li><li>API03 \u2013 Retrieve File from Device<\/li><li>API15 \u2013 Verify StayLinked<\/li><\/ul>\n\n\n\n<h4>Host API Configuration Options<\/h4>\n\n\n\n<p>There are a few options that you can configure to control the behavior and processing of the StayLinked Host APIs. The options are available in the \u2018Telnet Host Entry\u2019 dialog in the \u2018Host API Configuration\u2019 section. If you open your \u2018Telnet Host Group\u2019 and then update one of the \u2018Telnet Host Entries\u2019 you will be presented with this dialog:<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" width=\"385\" height=\"599\" src=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1.jpg\" alt=\"\" class=\"wp-image-1865\" srcset=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1.jpg 385w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1-193x300.jpg 193w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1-32x50.jpg 32w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1-39x60.jpg 39w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1-64x100.jpg 64w\" sizes=\"(max-width: 385px) 100vw, 385px\" \/><\/figure>\n\n\n\n<p><strong>Separator Char<\/strong><br>You can configure the screen character that the StayLinked Server will look for to identify the Host API String and to separate the arguments for the specific API command. The default separator character is a tilde (~) defined with an ASCII value of 0x7E in hexadecimal notation. If you must use a different separator character, then you can specify the ASCII value in hexadecimal notation.<\/p>\n\n\n\n<p><strong>Host API Row \/ Col<\/strong><br> You can configure the row and column on the application screen where the StayLinked Server will look for the \u2018API Identifier\u2019 which always starts with the separator character (~). The default values are Row 1 and Column 2. If the server processes a \u2018presentation space event\u2019 that includes the specified row and column, then the server will look for the \u2018API Identifier\u2019 string at this location. The API Identifier string will start with a separator character (~), followed by the capital letters \u2018API\u2019 and then the&nbsp; two-digit API Number. Here are some example API signatures: ~API01, ~API12, etc.<\/p>\n\n\n\n<p><strong>Show API<\/strong><br> By checking this box, you can configure the Host API processing to cause the \u2018presentation space event\u2019 that includes a Host API to be displayed on the device if needed. The default for this setting is to NOT display any \u2018presentation space event\u2019 that includes a Host API. Depending upon how you have written the screen logic in your application and how you display Host APIs in your application, you may need to display Host API screens on the device or not.<\/p>\n\n\n\n<h4>A Sample Host API Screen<\/h4>\n\n\n\n<p>The various StayLinked<strong> <a href=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api-2\/\">Host APIs<\/a><\/strong> have different requirements \u2013 some need inputs, some provide outputs, some have both, and some have neither. But all of the API screens have one thing in common \u2013 a specific set of characters (~API##) at the top of the screen. This is the API Identifier which is used to identify the Host API screen to the StayLinked Server. The following screen sample illustrates an API that requires both inputs and outputs:<\/p>\n\n\n\n<figure class=\"wp-block-image is-resized\"><img loading=\"lazy\" src=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2.jpg\" alt=\"\" class=\"wp-image-1866\" width=\"637\" height=\"377\" srcset=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2.jpg 397w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2-300x178.jpg 300w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2-50x30.jpg 50w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2-60x36.jpg 60w, https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.2-100x59.jpg 100w\" sizes=\"(max-width: 637px) 100vw, 637px\" \/><\/figure>\n","protected":false},"excerpt":{"rendered":"<p>API Types APIs are available within StayLinked in three different types. APIs are available within Screen Recognition. This is the most common use and primary area for implementing APIs. Starting in server version 15.3 there are session settings that include API options at the Start, Reconnection (requires server v15.5), Global&#8230;<\/p>\n","protected":false},"author":7,"comment_status":"open","ping_status":"closed","template":"","format":"standard","meta":[],"ht-kb-category":[42],"ht-kb-tag":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v16.5 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>StayLinked Application Programming Interface (API) Options &ndash; StayLinked<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.staylinked.com\/knowledge-base\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"StayLinked Application Programming Interface (API) Options &ndash; StayLinked\" \/>\n<meta property=\"og:description\" content=\"API Types APIs are available within StayLinked in three different types. APIs are available within Screen Recognition. This is the most common use and primary area for implementing APIs. Starting in server version 15.3 there are session settings that include API options at the Start, Reconnection (requires server v15.5), Global...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/\" \/>\n<meta property=\"og:site_name\" content=\"StayLinked\" \/>\n<meta property=\"article:modified_time\" content=\"2024-07-22T14:58:51+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1.jpg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"8 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebSite\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/#website\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/\",\"name\":\"StayLinked Knowledge Base\",\"description\":\"Partner Portal Resources and Support\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":\"https:\/\/portal.staylinked.com\/sl\/kb\/?s={search_term_string}\",\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"ImageObject\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/#primaryimage\",\"inLanguage\":\"en-US\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1.jpg\",\"contentUrl\":\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/11\/HostAPI_1.1.jpg\",\"width\":385,\"height\":599},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/#webpage\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/\",\"name\":\"StayLinked Application Programming Interface (API) Options &ndash; StayLinked\",\"isPartOf\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/#primaryimage\"},\"datePublished\":\"2019-11-07T22:33:16+00:00\",\"dateModified\":\"2024-07-22T14:58:51+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/host-application-programming-interface-api\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/portal.staylinked.com\/sl\/kb\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Articles\",\"item\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"StayLinked Application Programming Interface (API) Options\"}]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","_links":{"self":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1864"}],"collection":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/comments?post=1864"}],"version-history":[{"count":10,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1864\/revisions"}],"predecessor-version":[{"id":4926,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1864\/revisions\/4926"}],"wp:attachment":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/media?parent=1864"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb-category?post=1864"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb-tag?post=1864"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}