N201 V10 IsatData Pro Gateway Web Service Guide

IsatData Pro Gateway Web Service (IGWS)
User Guide
N201, Version 10
The electronic version of this document allows

you to use the built-in Hyperlinks and
bookmarks when using Adobe Reader
© SkyWave Mobile Communications Inc.

Aug 2014
IsatData Pro Gateway Web Service (IGWS) - User Guide
Legal Notice
This documentation is owned by SkyWave Mobile Communications Inc. (SkyWave) and protected by
applicable copyright laws and international treaty provisions. Other copyrighted names used are the property
of their respective owners. Therefore, you must treat this documentation like any other copyrighted material.
You may not make the documentation, or copies thereof, available in any manner or form, or use, copy or
transfer any part, to anyone outside your company.
If you received this documentation by electronic transmission or download, by installation or use of the
documentation, you acknowledge that you have read and understand this license agreement and agree to be
bound by its terms and conditions.
This documentation is provided on an as-is basis without any warranty of any kind. You assume the entire
risk as to the results or performance of the software. Under no circumstance shall SkyWave be held liable for
any direct, indirect, consequential, or incidental damages arising from the use or inability to use the software
or documentation.
All trademarks or registered trademarks are the property of their respective owners. INMARSAT, the
Inmarsat logo and IsatData Pro are trademarks of Inmarsat used under license by SkyWave. Inmarsat is not
responsible for the operation and regulatory compliance of the products and services referred to in this
document that connect to the Inmarsat system.
SkyWave reserves the right to make changes to products and or specifications without notice.
From www.SkyWave.com login, and follow the link to the downloads section. The complete Software and
Documentation License Agreement is distributed as a part of the IDP Toolkit.
Contact Information
SkyWave Mobile Communications Inc.
Online:
 Website www.SkyWave.com
Online Documentation:
 Login at support.skywave.com and follow the link to the downloads section
Customer Support by Email:
 support@skywave.com
Customer Support by Telephone:
 +1.613.836.2222
Documentation Feedback:
The Customer Documentation Department creates the SkyWave technical manuals.
Use the address below to tell us what you think about our technical documentation
and if you have suggestions for improvement.
In your feedback please reference a specific document number or title. We read all
feedback carefully, but please note that we cannot respond to the comments you
submit. If you require technical assistance, please contact SkyWave Customer
Support.
 documentation@skywave.com
N201, Version 10 ii © SkyWave Proprietary

TABLE OF CONTENTS
Legal Notice.................................................................................................................................... ii
Contact Information...................................................................................................................... ii
TABLE OF CONTENTS ............................................................................................................. iii
List of Figures ................................................................................................................................ v
Preface .......................................................................................................................................... vii
What's New? ............................................................................................................................... vii
Purpose ....................................................................................................................................... vii
Errata Sheet ................................................................................................................................. vii
Audience ..................................................................................................................................... vii
Notation ...................................................................................................................................... vii
Reference .................................................................................................................................... vii
1 Introduction ......................................................................................................................... 1
2 Overview .............................................................................................................................. 2
2.1 Terminals ............................................................................................................................ 2
2.1.1 Low Power Mode ............................................................................................................ 3
2.2 Gateway Accounts .............................................................................................................. 3
3 The IGWS Protocol............................................................................................................. 6
3.1 Submitting Messages .......................................................................................................... 7
3.1.1 Submitting Messages to Terminals in Low Power Mode ................................................ 7
3.1.2 Message Timeout ............................................................................................................. 7
3.2 Getting Your Messages ...................................................................................................... 8
3.2.1 Message Retention ........................................................................................................... 9
4 Web Service Application Programming Interface ......................................................... 10
4.1 Get Operations.................................................................................................................. 10
4.1.1 GetBroadcastInfos ......................................................................................................... 10
4.1.2 GetForwardMessages..................................................................................................... 11
4.1.3 GetForwardStatuses ....................................................................................................... 11
4.1.4 GetMobilesPaged ........................................................................................................... 11
4.1.5 GetReturnMessages ....................................................................................................... 11
4.1.6 GetSubaccountInfos ....................................................................................................... 12
4.2 Information Operations .................................................................................................... 12
4.2.1 InfoErrorInfos ................................................................................................................ 12
4.2.2 InfoUTC ......................................................................................................................... 12
4.2.3 InfoVersion .................................................................................................................... 12
4.3 Submit Operations ............................................................................................................ 12
4.3.1 SubmitForwardMessages ............................................................................................... 14
4.3.2 SubmitForwardMessageToMultipleDestinations .......................................................... 14
4.3.3 SubmitMessageCancelations ......................................................................................... 14
5 Common Message Format................................................................................................ 16
5.1 Common Message Fields ................................................................................................. 17
5.1.1 Common Message Example .......................................................................................... 18
6 Classes ................................................................................................................................ 19
© SkyWave Proprietary iii N201, Version 10

6.1 Get Classes ....................................................................................................................... 19

6.2 Information Classes .......................................................................................................... 21
6.3 Submission Classes .......................................................................................................... 22
7 Code Samples .................................................................................................................... 26
7.1 Creating a Web Service Proxy Instance and Setting the URL ......................................... 26
7.2 Retrieving Account Information....................................................................................... 27
7.3 Submitting a To-Mobile Message .................................................................................... 29
7.4 Querying for a To-Mobile Message Status ...................................................................... 32
7.5 Polling for From-Mobile Messages Using a Timestamp as a High Watermark............... 34
7.6 Polling for From-Mobile Messages Using a Message ID as a High Watermark ............. 36
8 REST Web Service Interface ........................................................................................... 38
8.1 info_utc_time.................................................................................................................... 38
8.2 info_errors ........................................................................................................................ 39
8.3 info_version ...................................................................................................................... 40
8.4 get_subaccount_infos ....................................................................................................... 41
8.5 get_broadcast_infos .......................................................................................................... 42
8.6 get_mobiles_paged ........................................................................................................... 43
8.7 get_return_messages ........................................................................................................ 44
8.8 get_forward_statuses ........................................................................................................ 47
8.9 get_forward_messages ..................................................................................................... 49
8.10 submit_messages .............................................................................................................. 51
8.11 submit_messages_to_destinations .................................................................................... 53
8.12 submit_cancelations ......................................................................................................... 55
9 Tutorial – SOAP Based Web Service .............................................................................. 57
9.1 Getting Started.................................................................................................................. 57
9.2 Required Materials and Equipment .................................................................................. 57
9.3 Creating and Configuring a New Project ......................................................................... 57
APPENDIX A Common IGWS Error Codes......................................................................... 61
APPENDIX B Interface Test System ...................................................................................... 64
APPENDIX C Web Service Client Development Best Practices.......................................... 65
APPENDIX D Interface Code Description ............................................................................ 69
C# .NET SOAP Client Sample ................................................................................................... 69
Java SOAP Client Sample .......................................................................................................... 70
Acronyms/Glossary ..................................................................................................................... 71
Revision History .......................................................................................................................... 72
N201, Version 10 iv © SkyWave Proprietary

List of Figures
Figure 1 Gateway Interface ........................................................................................................ 1
Figure 2 IGWS in the Context of the Network .......................................................................... 2
Figure 3 Multiple Clients ........................................................................................................... 2
Figure 4 Mobile and Subaccount IDs ........................................................................................ 4
Figure 5 Subaccounts Relationship ............................................................................................ 5
Figure 6 Overview of IGWS ...................................................................................................... 6
Figure 7 Submitting Messages ................................................................................................... 8
Figure 8 Getting Messages......................................................................................................... 9
Figure 9 Gateway Interface ...................................................................................................... 10
Figure 10 Message States........................................................................................................... 13
Figure 11 Common Message Format ......................................................................................... 16
Figure 12 Get Classes ................................................................................................................ 19
Figure 13 Information Classes ................................................................................................... 21
Figure 14 Message Submission Classes..................................................................................... 22
Figure 15 To-Mobile Message Related Classes ......................................................................... 23
Figure 16 Debug Information after InfoErrorInfos Call ............................................................ 28
Figure 17 Sample Error Message ............................................................................................... 28
Figure 18 Debug Information after Message Submission.......................................................... 32
Figure 19 Debug Information after Message Status .................................................................. 33
Figure 20 Debug Information for From-Mobile Messages ........................................................ 35
Figure 21 Gateway Polling Result ............................................................................................. 36
Figure 22 New Visual Studio Project ........................................................................................ 58
Figure 23 Add a Service Reference ........................................................................................... 58
Figure 24 Service Reference Settings ........................................................................................ 59
Figure 25 Enter the URL............................................................................................................ 59
Figure 26 IGWS Sample Code .................................................................................................. 60
© SkyWave Proprietary v N201, Version 10

THIS PAGE INTENTIONALLY LEFT BLANK
N201, Version 10 vi © SkyWave Proprietary

Preface
What's New?
Changes since the last release of this document are listed below.
 Updates to details regarding getting messages (Section 3.2)
 Updated InfoErrorInfos description (Section 4.2.1) and ErrorInfo description
(Section 6.2)
 Updated descriptions for StarMessageID, NextStartID, and NextStartUTC
(Section 6.1)
 Updated notes section for SubmitMessageCancelations (Section 4.3.3)
 Updated code example in Section 7.6
 Added To-Mobile Message Failure Error Codes to APPENDIX A.
 Updated code examples in APPENDIX C.
 Minor edits and updates throughout.
Purpose
This document provides an overview of the IsatData Pro Gateway Web Service for
developers as well as defines the IsatData Pro Web Service interface.
Errata Sheet
Refer to the SkyWave Customer Support website for any updates or a possible Errata
Sheet available after the release of this document. Always check the site for the most
current documentation releases or readme documents.
Audience
This document is for technical readers.
Notation
IsatData Pro Gateway Web Service is platform independent. Many code examples in this
document are in C# for .NET Framework 3.5 or higher using Microsoft® Visual Studio®
2008.
A forward message is a message sent to the terminal from the gateway, while a return
message is one sent from the terminal.
Reference
It is recommended that you be familiar with the content of the following documents
before using this guide. These SkyWave documents are available from the IDP Toolkit or
support.skywave.com.
© SkyWave Proprietary vii N201, Version 10

[N200] IsatData Pro Network Services Overview

[N206] IsatData Pro Cellular Protocol
[T203] IDP-110/IDP-180/IDP-190 Developer Guide
[T202] IDP-680/IDP-690 and IDP-800 API Reference Guide
[T208] IDP-780 flex/IDP-790 flex API Reference Guide
Please refer to the embedded help file in each of the following software tools for
additional information. These tools are available from the IDP Toolkit.
 Developer Studio
N201, Version 10 viii © SkyWave Proprietary

1 Introduction
SkyWave's IsatData Pro network provides messaging services between terminals and an
Internet application. This document defines the IsatData Pro Gateway Web Service
(IGWS) protocol that SkyWave's customers can use to submit and retrieve messages to
and from their terminals from their Internet application.
IGWS supports both the SOAP and the RESTful style of web services, and is therefore
platform and language-independent allowing for easy integration with a customer's back
office system.
SOAP based web service describes its interfaces in enough detail to enable a user to build
a client application to talk to it. This description is provided in an XML document called a
Web Services Description Language (WSDL) file.
The WSDL file describes the complete contract for application communication. SOAP
based web service makes Web services widely approachable by using WSDL definitions
to generate code that knows precisely how to interact with the Web service described, and
hides tedious details in sending and receiving SOAP messages over different protocols.
A RESTful web service is a simple web service implemented using HTTP and the
principles of REST. RESTful applications use HTTP requests to post data (create and/or
update), read data (e.g., make queries), and delete data. It is particularly useful for limited-
profile devices such as PDAs and mobile phones, for which the overhead of headers and
additional layers of SOAP elements on the XML payload must be restricted.
The IGWS supports both JSON and XML encoding with its REST interface.
This document describes mostly the SOAP based web service and data structures
provided by it. Section 8 describes the REST based web service. Data structures
exchanged by the REST web service are the same as for SOAP.
Modem messages are described in [T203].
Figure 1 Gateway Interface
Client Applications IGWS Interface
SkyWave Proprietary 1 N201, Version 10

2 Overview
Figure 2 shows the position of the IsatData Pro Gateway Web Service (IGWS) in the
message chain.
Figure 2 IGWS in the Context of the Network
Customer’s Servers / server applications
IsatData Pro Gateway
End user applications IGWS

talking to customer’s
back office servers
End user applications
talking directly to the
web service
End user applications
Applications range from a back office server exchanging messages with the web service
and providing messages to its own client applications, to desktop/mobile applications
talking directly to the web service.
Multiple clients can access the same account on the Gateway. Any Gateway account
restrictions such as polling or submission rates apply to the account; not to the client.
Figure 3 Multiple Clients
Customer
AccessID: 60001 Mobile 1

Server 1
Gateway account Mobile 2

AccessID: 60001
AccessID: 60001
Server 2
Mobile 3
Desktop
application AccessID: 60001 Gateway Web Service
Each client must maintain its own high watermark in order to extract messages in
sequence. The Gateway uses high watermarks to return the latest messages to client
applications. Along with the latest messages, the Gateway returns the next high
watermark. The client must save this high watermark and use it for its next access.
2.1 Terminals
A terminal must be activated in order send and receive messages. Terminals can be
activated using the SkyWave Customer Support website (support.skywave.com). A
terminal can only be activated in a single Gateway account.
N201, Version 10 2 © SkyWave Proprietary

2.1.1 Low Power Mode

Terminals can be optionally configured for low power operation. When a terminal is
configured for low power, it periodically wakes up for one minute and checks for to-
mobile messages. The terminal's low power configuration is stored by the Gateway. If the
terminal is configured for low power, the Gateway stores all to-mobile messages and
delivers them when it knows the terminal is awake.
The wake-up period can be configured both over-the-air (OTA) and locally at the
terminal. To change the wake-up period over-the-air, the application must send an
UpdateSleepSchedule system message. It is the application's responsibility to
ensure that the terminal receives and acknowledges the messages. If the terminal does not
respond, the application must resend the message. When the wake-up period is changed
locally at the terminal, the terminal transmits a ResponseSleepSchedule message.
The Gateway forwards the message to the application and it uses this message to set the
wake-up period for the terminal. In order to ensure the terminal and Gateway stay
synchronized, the system registration message, as well contains the wake-up interval.
Table 1 outlines the wake-up periods supported by IsatData Pro. Although the application
can configure the wake-up period, the terminal's wake-up time is selected based on its
mobile ID.
Table 1 IsatData Pro Wake-up Periods
Value Wake-up Period
0 5 second receives
1 30 second receives
2 1 minute receives
3 3 minute receives
4 10 minute receives
7 2 minute receives
8 5 minute receives
More details on the System messages to configure the wake-up interval can be found in
[T203].
2.2 Gateway Accounts

Every Gateway customer has an account on the Gateway (Figure 4) made up of the
following:
 Credentials in the form of access ID/password pair
 Set of mobile IDs
 Set of broadcast IDs
 Set of subaccount IDs
 Message definitions

Message definitions are used by the IDP Gateway to encode to-mobile message
payloads and decode from-mobile message payloads. This allows bit-efficient
transport of data over the IDP satellite network, yet allows the Gateway to present
an interface which consists of named fields of various data types.
Message definition files are created using the Developer Studio tool found in the
IDP Toolkit.
Upload and manage your message definition file from the SkyWave Customer
Support website (Online Utilities link) if you want the Gateway to decode your
messages. If the Manage Message Definition Files option is not available to you,
contact SkyWave Customer Support for assistance.
A Gateway customer can:
 Send messages to terminals associated with its account or subaccounts
 Broadcast messages to groups of terminals represented by a broadcast ID
associated with its account or subaccounts
 Retrieve messages from terminals associated with its account or subaccounts
Figure 4 Mobile and Subaccount IDs
Gateway Account
Mobile IDs
Access ID/password
Access limits
Account information
Broadcast IDs
Subaccounts
A subaccount is a separate Gateway account (Figure 5) that a Gateway customer can

access using their own access ID and password. If a Gateway account contains one or
more subaccounts, it means that clients accessing this account can send and receive
messages to terminals belonging to other Gateway accounts (its subaccounts). The
customer must explicitly provide the optional subaccount ID to send or receive messages
to the subaccount's mobile IDs or broadcast IDs. For example, if account B is not a
subaccount of account A, clients accessing account A are unable to send receive messages
to account B's mobile IDs or broadcast IDs.

Figure 5 Subaccounts Relationship

Gateway account
Mobile IDs
Access ID/password
Access limits
Account information
Broadcast IDs
Gateway account
Subaccount IDs Mobile IDs

Access ID/password
Access limits
Account information
Broadcast IDs
Gateway account
Mobile IDs
Access ID/password
Access limits
Account information
Broadcast IDs
Every subaccount ID points to another Gateway account with its own set of mobile IDs
and broadcast IDs. A subaccount for one Gateway user could be the primary account for
another Gateway user, i.e. a subaccount can have its own further subaccounts. An account
with subaccount A does not inherit the subaccounts of account A. This means that a
Gateway account can only send/receive messages to terminals belonging to itself or its
subaccounts.
From-mobile message billing is done for the Gateway account to which the terminal
belongs. If a message is sent from a terminal, the account where the terminal is activated
is billed, regardless if the from-mobile message was requested by a to-mobile message
from a different account.
By default, to-mobile message billing is processed for the Gateway account to which the
terminal belongs. Contact SkyWave Customer Support if you wish to change this billing
behavior.
Account and subaccount IDs must be provisioned by SkyWave Customer Support. They
cannot be provisioned by SkyWave's customers.

3 The IGWS Protocol

The SOAP based IGWS protocol is defined by its WSDL file. The WSDL can be obtained
directly from the IsatData Pro Gateway Web Service.
The URL, of the IsatData Pro Gateway Web Service is
https://isatdatapro.skywave.com/GLGW/GWServices_v1/Messages.svc.
The WSDL file's URL is
https://isatdatapro.skywave.com/GLGW/GWServices_v1/Messages.wsdl.
This file allows the software development tools to create proxy classes used to access the
web service (refer to the Tutorial in Section 9 for further details).
If http: is used, the access ID/password pair is sent as a clear text over the network. It is
recommended to use the https: URL to communicate with the Gateway if security is a
concern.
Figure 6 describes the basic usage of IGWS. A typical client server application loads all
relevant account information from IGWS when initialized, and it starts submitting
messages and polling on regular intervals.
Figure 6 Overview of IGWS
Client Application IGWS
SubmitForwardMessage()
SubmitMessagesResult
GetReturnMessages()
GetReturnMessagesResult
GetReturnMessages()
SubmitForwardMessage()
SubmitMessagesResult
GetReturnMessages()
The RESTful web service interface can be used in the same way, but with different web
service URLs (Section 8).
Note: SkyWave periodically updates the IGWS web service to improve
functionality. Such updates could potentially include the addition of new

fields to existing classes and/or new web service methods however existing
fields or methods remain functional. Client applications accessing the
IGWS web service must be capable of handling such updates.
Note: SkyWave provides a test system with the updated web service interface at
least 30 days before the update. Customers are encouraged to test their
applications in advance of the upgrade using this test system. Test system
documentation (N201-ADA IsatData Pro Test Interface Addendum) is
available on the SkyWave Customer Support website under
Downloads>IsatData Pro>Network Docs.
3.1 Submitting Messages

The client application prepares a message to be submitted to a terminal and uses one of
the Submit web service operations (Section 4.3) to submit it. If the IGWS accepts the
message, the client application receives a Gateway generated message ID of the submitted
message; otherwise the client receives an error code.
To submit messages, the client application must provide its access ID/password pair with
each web service call. In the event invalid credentials are submitted, the web service
returns an error.
To map the client application's message IDs to the Gateway generated message IDs, client
applications can optionally submit a UserMessageID with the message. The
UserMessageID is returned as a response (Figure 7) together with a
ForwardMessageID generated by the Gateway.
3.1.1 Submitting Messages to Terminals in Low Power Mode

Messages submitted to terminals that are in the low power mode are not transmitted to the
terminal immediately. These messages are scheduled to be transmitted during the
terminal’s next wake-up period.
3.1.2 Message Timeout

If a terminal is blocked and a to-mobile message cannot be delivered, the Gateway closes
the message. The following table shows how long, after the message has been transmitted,
it takes the Gateway to close the message if it cannot be delivered.
Terminal mode Terminal fully blocked Terminal intermittently blocked
Regular Up to 10 minutes Up to 60 minutes
Low power Up to 10 minutes from the Up to 60 minutes from the
scheduled send time scheduled send time
Refer to Section 4.3 for more information on message states.

Figure 7 Submitting Messages
Client application Gateway web service
SubmitForwardMessage(accessID, password, message, UserMessageID)
Checks credentials
Checks the message destination
Verifies the message content

ForwardMessageID, UserMessageID
Sends the message out
Check for errors
3.2 Getting Your Messages

To start polling the Gateway, a client application typically uses the Gateway's current time
as a first high watermark. The subsequent high watermarks are returned with each
successful GetReturnMessages call. GetReturnMessages calls that are not successful
(responses ErrorCode > 0) or calls that do not return messages do not contain a valid next
high watermark in the response.
You specify a high watermark as part of a message filter (ReturnMessageFilter object -
see section 6.1) for the SOAP web service interface, or as a parameter for REST web
service interfaces.
Client applications should always store the last valid high watermark and use it in
subsequent calls. A message ID (StartMessageID) is a preferred way, but timestamps
(StartUTC, EndUTC) can be used as well, especially if you want to query messages from
a specific timeframe in the past or when the client application starts for the very first time
and you still do not have a valid starting high watermark.
To receive messages related to only one terminal, a specific mobile's ID can be set in the
message filter.
The message filter can also optionally restrict extraction of messages received during a
specific period of time specified by a from and to timestamp.
If a call to the GetReturnMessages produces more messages than can fit in a single
response (500 messages), the More field is set to true in a
GetReturnMessagesResponse. At usual, a new high watermark is returned, so that
the next GetReturnMessages call can pick the remaining messages.
When the Get call returns, it provides new high watermark information that the client
application uses for the next call.
Figure 8 shows a client application polling the web service for response messages. The
client application needs to pass account credentials and message filter information. The

high watermark is part of the message filter. With every call to the Gateway's
GetReturnMessages, the client application needs to provide at least high watermark
information.
Figure 8 Getting Messages
Client application Gateway web service
GetReturnMessages(accessID, password, high watermark)
Checks credentials
Retrieve messages
Messages, error ID, next high watermark...
Check for errors
Store messages
Check for errors
Store messages
In the event that a problem is encountered when storing received messages, the client
application can be written to request previous high watermarks.
3.2.1 Message Retention

IsatData Pro allows the retrieval of from-mobile messages for up to five days. Any
customer application requiring access to messages older than five days must retrieve the
messages when available and store them locally for later retrieval.

4 Web Service Application Programming Interface

The following class diagrams represent classes that are defined within the web service's
WSDL file. These classes are generated by development tools supporting SOAP based
web services.
GatewayInterface class is the main web service class containing all web service
operations. An instance of this class needs to be created in order to invoke web service
operations. There are three main SkyWave categories for operations: get, information and
submit. Figure 9 lists all operations of the IGWS interface.
Figure 9 Gateway Interface
4.1 Get Operations

This section lists all of the get operations provided by the IsatData Pro Gateway Web
Service. The class definitions associated with the get operations are described in
Section 6.1.
The Gateway restricts the frequency that clients can call Get operations of the web
service. A reasonable access rate for customers with many terminals would be up to 20
times within any 10 second period. Accessing the web service more frequently may be
rejected. If a web service user calls the web service too often, the web service
immediately returns an error (error code 16:ERR_CUSTOMER_DELAYED).
4.1.1 GetBroadcastInfos
Description This operation returns a list of broadcast ID information that was
assigned to the account or subaccount (if subaccountID is specified).
Syntax GetBroadcastInfosResult GetBroadcastInfos (String
accessID, String password, String subaccountID) ;

4.1.2 GetForwardMessages
Description Retrieves to-mobile message records defined by an array of to-mobile
message IDs (ForwardMessageIDs). If you specify the
subaccountID, the method returns to-mobile messages belonging to that
subaccount.
Syntax GetForwardMessagesResult
GetForwardMessages(String accessID, String
password, int[] ForwardMessageIDs, String
subaccountID);
Notes The maximum number of to-mobile IDs is 100 by default.
4.1.3 GetForwardStatuses
Description Retrieves to-mobile message statuses defined by the
ForwardStatusFilter object.
Syntax GetForwardStatusesResult
GetForwardStatuses(String accessID, String
password, ForwardStatusFilter filter);
Notes The maximum default number of returned statuses is 500 if you are
querying by a timestamp or 100 if you are querying by message IDs (see
description for ForwardStatusFilter in Section 6.3).
4.1.4 GetMobilesPaged
Description This operation returns a list of information about the terminals that were
assigned to the account or subaccount (if subaccountID is specified).
Syntax GetMobilesPagedResult GetMobilesPaged (String
accessID, String password, String subaccountID, String sinceMobile, int
pageSize);
Notes GetMobilesPaged returns a maximum of pageSize MobileExInfo
records.
Range of the pageSize's parameter is 1 to 1000.
Result records are sorted by mobile's serial number.
First call to the GetMobilesPaged sets sinceMobile parameter to
an empty string, and all subsequent calls set it to the serial number of the
terminal from the end of the previous call's result.
4.1.5 GetReturnMessages
Description Retrieves from-mobile messages defined by the
ReturnMessageFilter filter.
Syntax GetReturnMessagesResult GetReturnMessages(String
accessID, String password, ReturnMessageFilter
filter);
Notes GetReturnMessages returns a maximum of 500 messages. Refer to
Section 3.2.1 for message retention details. Refer to sections 3.2, 6.1,
7.5, 7.6 and APPENDIX C for more details and sample code snippets.

4.1.6 GetSubaccountInfos
Description Returns an array of all subaccount information associated to the client
account.
Syntax GetSubaccountInfosResult
GetSubaccountInfos(String accessID, String
password);
4.2 Information Operations

This section provides the information operations available on the Gateway interface.
4.2.1 InfoErrorInfos
Description InfoErrorInfos returns an array of errors information defined by
the Gateway. This web service operation can be called by a back office
server application during its initialization sequence to create a dictionary
of all available Gateway error codes. This dictionary allows your back
office application to get both the name and the description of an error
returned by the Gateway. Refer to section 6.2 for more information
about the ErrorInfo structure. Refer to section 7.2 to see a sample code
showing the use of this operation.
APPENDIX A lists common Gateway error codes.
Syntax ErrorInfo[] InfoErrorInfos();
4.2.2 InfoUTC
Description This operation returns the Gateway time in UTC.
Syntax String InfoUTC();
Notes Use this method as a starting point in regular Gateway polling. For
example, it can be used as StartUTC of the
ReturnMessageFilter.
All timestamps exchanged between the client and the Gateway use the
following UTC format:
YYYY-MM-DD hh:mm:ss.
For example: 2010-12-18 07:22:15 is December 18th 2010 at 7:22:15
am.
4.2.3 InfoVersion
Description This operation returns a string with a version of the IsatData Pro
Gateway Web Service.
Syntax String InfoVersion();
4.3 Submit Operations

The maximum default submission rate per account is 20 submissions within a 10 second
period. If any Submit operation is called more frequently, the request is rejected. The
account restriction applies when multiple client applications are accessing the same
account.

The IsatData Pro Gateway limits the number of outstanding to-mobile message for each
terminal. If there are more than 20 outstanding to-mobile messages (consisting of a
maximum of 10 regular sized and 10 large sized messages) for a single terminal, the
Gateway rejects them and reports an error message.
A regular sized message has a payload of up to 5,000 bytes and a larger message has a
payload of more than 5,000 bytes.
Outstanding messages are messages that have not yet been acknowledged by a terminal.
The errors are:
ERR_REGULAR_MESSAGE_SIZE_QUEUE_FULL - there are already 10
outstanding regular size messages for this terminal.
ERR_LARGE_MESSAGE_SIZE_QUEUE_FULL - there are already 10 outstanding
large size messages for this terminal.
When a message is submitted it is in the open state and remains in this state until either a
response is received or an error condition causes the message to change to the closed
state. Figure 10 shows submit message states for a to-mobile message.
Figure 10 Message States
RECEIVED
ERROR
SUBMITTED DELIVERY_FAILED
TIMED_OUT
CANCELLED
Open states Closed states
A message has one of the following states:

Table 2 Message States
State Description
SUBMITTED Gateway has accepted the message.
RECEIVED The Gateway received an acknowledgement that the terminal
received the message.
ERROR The message closed due to an error. An error code specifies the
reason.
DELIVERY FAILED Gateway failed to deliver the message to a terminal. An error
code specifies the reason.

State Description
TIMED OUT Message failed to be delivered within 60 minutes. A normal state
when the message cannot be delivered is DELIVERY FAILED.
TIMED OUT. This state is required in case the message is still
not delivered 60 minutes after it was sent from the Gateway.
CANCELLED Message was successfully cancelled by the client application.
 Use GetForwardStatuses web operation to query the message state.
This section provides a list of Gateway operations used to submit messages. Class
information associated with the submit operations is given in Section 6.3.
4.3.1 SubmitForwardMessages
Description Submits multiple to-mobile messages to the Gateway.
Syntax SubmitMessagesResult
SubmitForwardMessages(String accessID, String
password, ForwardMessage[] messages);
Notes A maximum of 100 SubmitForwardMessages messages can be
submitted each call. The maximum size of each to-mobile message is
10,000 bytes for terminals not in low power mode and 5,000 bytes for
terminals with low power mode enabled.
4.3.2 SubmitForwardMessageToMultipleDestinations
Description Submits a to-mobile message to the Gateway to be sent to multiple
destinations.
Syntax SubmitMessagesResult
SubmitForwardMessageToMultipleDestinations(String
accessID, String password, ForwardMessage message,
String[] destinations);
Notes A maximum of 100 destinations can be specified in each call.
4.3.3 SubmitMessageCancelations
Description Submits cancelation messages to selected to-mobile messages defined in
the ForwardMessageIDs array.
Syntax SubmitMessageResult SubmitMessageCancelations
(String accessID, string password, int[]
ForwardMessageIDs);
Notes A cancelation message will not succeed if the to-mobile message was
already sent to the terminal.
An immediate success response returned by this call does not mean that a
to-mobile message has successfully been cancelled. It means that the
Gateway has successfully accepted the cancellation request. Success or
failure of the cancellation request can be determined by its final status (by
calling GetForwardStatuses).
For example, a position request message is sent with a forward ID of
2057799. To cancel the message you need to call
SubmitMessageCancelations and pass it an ID of 2057799 through its
ForwardMessageID argument. In the immediate response from the

Gateway, you receive a new forward message ID = 2057812. The new ID,
2057812, refers to the cancellation request message.
If you periodically poll for message status changes by calling
GetForwardStatuses, after a while, you receive a status for message
2057812. If the status is 'RECEIVED' and ErrorId is 0 it means that the
cancellation request has succeeded and that message 2057799 has been
cancelled. In that case you would eventually receive the status of that
message as 'CANCELLED' as well. However, if the ErrorId is not 0, but
for example 17685, it indicates that your cancellation request has failed
with error "17685 - Message cannot be cancelled because it has already
been sent to its destination".

5 Common Message Format

All IsatData Pro messages (both to-mobile and from-mobile) can be defined by a common
message format.
Figure 11 Common Message Format
Message Instances of this class represent the message in both the to-mobile and
from-mobile direction. Based on the message definitions, the Gateway
encodes/decodes messages from/to this form.
IsForward This field is relevant only if the message is part of another field. In that
case, the message is a to-mobile message if set to true. Otherwise it is a
from-mobile message.
MIN Message identification number for the given SIN
Name Message name
SIN Service identification number
Fields An array of Field (instances of the field class). Each Field could be made
of either a name/value pair, or contain another array of fields.
Field A field is made of a name/value pair or an array of elements. If the client

specifies both, the Gateway rejects the message.
Name Field name
Type Type of the field - refer to Table 3 for more details
Value Value of the field
Message A message embedded within a field
Elements Array of Element (instances of the element class)
Element Element indexed structure containing one or more fields

Index Element's index
Fields Element's fields
The following is a sample of a message payload in the XML form.
<Message SIN="2" MIN="20">
<Fields>
<Field Name="Form" Value="email" />
<Field Name="FormFields">
<Elements>

<Element Index="0">
<Fields>
<Field Name="Email" Value="me@me.com" />
<Field Name="Subject" Value="subject" />
</Fields>
</Element>
</Elements>
</Field >
</Fields>
</Message>
5.1 Common Message Fields

There are ten types of common message fields. The attributes and elements used are
determined by the field type, which is specified when the message is defined using
Developer Studio.
Table 3 Common Message Fields
Developer Type Attribute Value Attribute Elements
Studio (used by
Field Type Dynamic or
Property fields)
Enum enum Enumeration value None
Boolean boolean True or False None
Unsigned Int unsignedint Decimal number None
Signed Int signedint Decimal number None
String string String None
(refer to Table 4 to conform to
XML encoding rules)
Data data Base64 encoded data None
Array array None <Elements>
<Element Index=>
<Fields>
</Fields>
</Element>
</Elements>
Message message None <Message SIN= MIN= IsForward=>
<Fields>
</Fields>
</Message>
Dynamic (one of above) (depends on type) (depends on type)
Property (one of above) (depends on type) (depends on type)
XML encoding rules have many special characters that require encoding. It is
recommended that you use your programming language's XML libraries which conform
to these rules. If unavailable, encode the characters in Table 4 in the order shown.

Table 4 Common Characters

Character ASCII Code Name XML-Encoded Value
(Hex)
& 38 (26) Ampersand &
< 60 (3C) Lower-Then Sign <
> 62 (3E) Greater-Than Sign >
" 34 (22) Quotation Mark "
(Double)
' 39 (27) Apostrophe '
5.1.1 Common Message Example

Below is an example of a common message.
<Message SIN="128" MIN="1">
<Fields>
<Field Name="ExampleEnumField" Value="Blue" />
<Field Name="ExampleBooleanField" Value="True" />
<Field Name="ExampleUnsignedIntField" Value="123" />
<Field Name="ExampleSignedIntField" Value="-123" />
<Field Name="ExampleStringField" Value="Hello World" />
<Field Name="ExampleDataField" Value="AQID" />
<Field Name="ExampleArrayField">
<Elements>
<Element Index="0">
<Fields>
<Field Name="ExampleBooleanField" Value="False" />
</Fields>
</Element>
<Element Index="1">
<Fields>
<Field Name="ExampleBooleanField" Value="True" />
</Fields>
</Element>
</Elements>
</Field>
<Field Name="ExampleMessageField">
<Message SIN="192" MIN="2" IsForward="True">
<Fields>
<Field Name="ExampleUnsignedIntField" Value="123" />
<Field Name="ExampleSignedIntField" Value="-123" />
</Fields>
</Message>
</Field>
<Field Name="ExampleDynamicField" Value="Hello" Type="string" />
<Field Name="ExamplePropertyField" Value="3" Type="unsignedint" />
</Fields>
</Message>

6 Classes
This section lists all the class definitions for the get, set, and information operations.
6.1 Get Classes

The following class diagram presents all classes related to get operations for from-mobile
messages.
Figure 12 Get Classes
ReturnMessageFilter The client needs to create an instance of this class when it calls the
web service's GetReturnMessages operation.
IncludeRawPayload By default, the Gateway returns already decoded messages. If it
needs to get the message in a raw, binary form, the client needs to
set this field to true, otherwise, only a decoded message is returned.
MobileID If the client sets this field, the Gateway returns only messages from
that terminal.
StartMessageID If this field has a value larger than zero, the Gateway returns all
messages with an ID larger than that. Unless the StartUTC field
is set, this is a mandatory field. If the field is not set to a value
larger than zero, the operation is rejected. Refer to Section 3.2.1 for
message retention details. If StartUTC is set,
StartMessageID is ignored. Using StartMessageID as a high
watermark (instead of StartUTC) is preferred.
StartUTC This field defines the start timestamp of messages the client wants
to retrieve from the Gateway. Unless the StartMessageID field
is set to a value larger than zero, this is a mandatory field. If the
field is not included, the operation is rejected. Refer to Section 3.2.1
for message retention details. If StartUTC is set,

StartMessageID is ignored.
This field is not processed if the field IncludeAllSubacounts
is included and set to true.
EndUTC If the client sets this field the Gateway returns all the messages
between the StartUTC (including) and EndUTC (not including)
timestamps. If the client does not specify the EndUTC field, the
Gateway returns all messages up to the current time. (Section
4.2.2).
SubAccountID If the client sets this field to the subaccount ID of one of its
subaccounts, the Gateway returns only messages belonging to
terminals associated to that subaccount. If this field is left empty,
the client receives messages from terminals associated with its
account.
IncludeAllSubaccounts Set this field to true if you want to query messages that belong to
your account and all your subaccounts. Since this is an optional
Boolean field, if you want its value to be transferred to the
Gateway, you also need to set the
IncludeAllSubaccountsSpecified field to true.
For this field to work, StartMessageID field has to be used
instead of StartUTC and EndUTC fields.
IncludeAllSubaccountsSpecified Set this field to true if you want the IncludeAllsubaccounts
field to be sent to the Gateway.
IncludeType Set this field to true if you want the Payload to include field types
as well. Since this is an optional Boolean field, if you want its value
to be transferred to the Gateway, you also need to set the
IncludeTypeSpecified field to true.
IncludeTypeSpecified Set this field to true if you want the IncludeType field to be sent
to the Gateway.
GetReturnMessagesResult A class holding a response from a GetReturnMessages call.

ErrorID Contains an error number if the web service operation encountered
some problems or zero if it was successful
More True if more messages remain on the Gateway that match the given
return message filter
NextStartID Contains the value of the next StartMessageID that the client
needs to provide with GetMessageFilter to receive contiguous
messages. If the client is using time as a high watermark,
StartMessageID field of the message filter should be set to
zero (0). NextStartID value is valid, and can be used for the
next high watermark, only if it is bigger than zero. When a call to
GetReturnMessages returns no new messages, the value of the
NextStartID will be negative.

NextStartUTC Contains the value of the next StartUTC field that the client could
provide with its GetMessageFilter to receive contiguous
messages. If the client is using message IDs as a high watermark,
this field can be ignored.
Messages Array of ReturnMessage objects (i.e., from-mobile messages)
ReturnMessage Instance of this class contains a from-mobile message

ID ID of the from-mobile message. This ID is a unique number used
by the Gateway to reference a message.
MessageUTC The Gateway message timestamp. A time when the message
becomes available to customers.
MobileID Identification number of the terminal that sent the message
RawPayload This field contains the raw, binary payload of the message if the
IncludeRawPayload flag in the ReturnMessageFilter is
true
ReceiveUTC Time when the message was received by the earth station
RegionName The terminal's region name
SIN Message's service identification number. The SIN is also included
in the payload.
Payload The message payload. The payload includes the SIN and the MIN.
The format of the payload is defined in Section 5, refer to Message
class.
OTAMessageSize Over-the-air message size in bytes.
6.2 Information Classes

Several web service operations return instances of information classes. They provide
information related to the web service and a customer.
Figure 13 Information Classes
GetSubaccountInfosResult An instance of that class is returned when the client calls the
GetSubaccountInfos web service operation
ErrorID The number of the error or zero if the web service operation call
succeeded
Subaccounts An array of SubaccountInfo objects

SubaccountInfo Each SubaccountInfo object contains information about one of the

client subaccounts
AccountID This field contains the ID of the subaccount
Name Name of the subaccount
ErrorInfo Contains information about a Gateway error. Web service operation
InfoErrorInfos returns an array of objects of that type.
Description Description of the Gateway error
ID Identification number of the Gateway error code.
Name Name of the Gateway error
6.3 Submission Classes

Figure 14 shows a class returned by the Submit operation.
Figure 14 Message Submission Classes
When the client submits to-mobile messages to the Gateway, it is submitting instances of
the ForwardMessage class.
When the client queries content of the submitted messages, it gets instances of the
ForwardMessageRecord class.
When the client queries status of a to-mobile message, it gets instances of the
ForwardStatus class.
SubmitMessagesResult Returned after a call to a send message web service operation
ErrorID The error number of the error or zero if the web service operation call
succeeded
Submissions An array of ForwardSubmission objects
ForwardSubmission Each ForwardSubmission object contains information about one

submitted to-mobile message. In the event of an error (i.e., ErrorID ! = 0),
ForwardMessageID and StateUTC are null (i.e., not sent). However,

DestinationID and UserMessageID, if set, are returned from the request.

DestinationID The mobile ID or the broadcast ID where the message is sent
ErrorID Contains an error number or zero if the message was accepted by the
Gateway
FowardMessageID A unique ID of the to-mobile message generated by the Gateway. The
client must use the ForwardMessageID to query the status of the to-
mobile message.
OTAMessageSize Over the air message size in bytes.
StateUTC UTC based timestamp of state change
UserMessageID This is an optional field. When it is submitted with the message, the
Gateway returns this number to allow the client application to map its
local message IDs (i.e., UserMessageID) to Gateway generated IDs
(i.e., ForwardMessageID).
TerminalWakeupPeriod The terminal's wake-up period in seconds if it is in low power mode, or
zero (0) if it is not.
ScheduledSendUTC If the terminal is in low power mode, this field contains the scheduled
transmission time.
Figure 15 To-Mobile Message Related Classes
ForwardMessage A class that represents a to-mobile message

DestinationID Destination of the client message. This is either a terminal or a broadcast ID.
RawPayload Contains a byte array of raw payload that is submitted to its destination
unchanged. This payload has to follow the format of terminal messages. The
format of terminal messages is described in [N200].
UserMessageID The UserMessageID is the client's message identification number. The
client must provide a user message ID if they want to map it to the Gateway's

number - the ForwardMessageID in the FowardSubmission class. The

Gateway does not store the UserMessageID anywhere. This field is irrelevant
if the SubmitForwardMessageToMultipleDestinations web
service operation is called.
Payload An instance of the message class. Based on the client message definitions,
Gateway encodes this payload to a binary array (raw payload) and sends it to
its destination. The payload format is defined in Section 5 under Message
class.
ForwardStatusFilter This filter defines what statuses are returned by the

GetForwardStatuses web service operation
ForwardMessageIDs Array of message IDs (up to 100) whose statuses are returned by the
GetForwardStatuses
StartUTC If ForwardMessageIDs is null or empty, StartUTC needs to be set.
This field defines the start timestamp of to-mobile message statuses the client
wants to retrieve from the Gateway.
EndUTC This field defines the end timestamp of to-mobile message statuses the client
wants to retrieve from the Gateway. If this field is omitted, the Gateway
returns the most recent statuses (statuses since the StartUTC).
SubaccountID If the client sets this field to the subaccount ID of one of its subaccounts, the
Gateway returns only messages belonging to terminals associated to that
subaccount. If this field is left empty, the client receives messages from
terminals associated with its account.
ForwardStatus Instance of this class provides information about the status of the client to-
mobile message
ErrorID Contains an error number in the Gateway was not able to get the status of the
to-mobile message; otherwise it is zero if a status was successfully retrieved
ForwardMessageID This is the to-mobile message ID. The ForwardMessageID is generated
by the Gateway when the to-mobile message was first submitted.
IsClosed A Boolean value that is true if the message has been closed or false if the
Gateway is still expecting acknowledgment on this message
ReferenceNumber Message reference number. Some from-mobile messages can contain this
number. It can be used to link to- and from-mobile messages.
StateUTC A UTC timestamp of the state field defined in this class. The state is the latest
state of the to-mobile message
State The latest state of the to-mobile message. For a list of states refer to Table 2.
GetForwardMessagesResult Instance of this class is returned when a client calls the

GetForwardMessages web service operation
ErrorID An error number if there was an error getting the requested
messages; otherwise it is zero
Messages Array of ForwardMessageRecord

ForwardMessageRecord Objects of this class contain to-mobile message information

CreateUTC Time the message was created on the Gateway
DestinationID The mobile ID or broadcast ID of the message
ErrorID An error number if the Gateway was not able to get the to-mobile
message or zero if a message was successfully retrieved
ID ID of the message. This is the message ID assigned by the Gateway
when the message was first submitted.
IsClosed True if the message has been closed, or false if it is still open
RawPayload Raw message payload
Payload An instance of the message class.
ReferenceNumber Message reference number. Some from-mobile messages can
contain this number. It can be used to link to- and from-mobile
messages.
StatusUTC UTC based timestamp of the message status
State The latest state of the message
GetForwardStatusesResult A class holding a response from a GetForwardStatuses call

ErrorID Contains an error number if the web service operation encountered
some problems or zero if it was successful
More True if more statuses remain on the Gateway that match the given
status message filter
NextStartUTC Contains the value of the next StartUTC field that the client needs
to provide with its ForwardStatusFilter to receive
contiguous messages
Statuses Array of ForwardStatus objects

7 Code Samples
This section presents and describes sample .NET C# code using the IsatData Pro Gateway
Web Service (IGWS).
7.1 Creating a Web Service Proxy Instance and Setting the URL
The following sample shows how to initialize the web service proxy.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using IGWSSamples.IGWS;
namespace IGWSSamples
{
class Program
{
static void Main(string[] args)
{
WebServiceTest test = new WebServiceTest();
test.InitWSAccess();
}
}
/// <summary>
/// Initialize the client web service proxy
/// </summary>
class WebServiceTest
{
private IGWS.IGWS SVC;
private String myAccessID;
private String myPassword;
public void InitWSAccess()

{
// Create an instance of the web service proxy class
SVC = new IGWS.IGWS();
// Set the web service URL

SVC.Url = @"http://isatdatapro.skywave.com/GLGW/GWServices_v1/Messages.svc";
// Set the time the Web service client waits for a synchronous
// XML Web service request to complete (in milliseconds).
// If not set, the default value is 100000 milliseconds.
SVC.Timeout = 30*1000; // Set it to 30 seconds for this sample
// Set the access ID and password that has been assigned to the client
myAccessID = "testUserID";
myPassword = "samplePassword";
}
}
}

7.2 Retrieving Account Information

After initializing the web service proxy, the client can get some information from the
IGWS that it might need in the application.
The following code sample shows how to get the list of all Gateway error codes and a list
of terminals associated to the client account.
namespace IGWSSamples
{
class Program
{
static void Main(string[] args)
{
WebServiceTest test = new WebServiceTest();
test.InitWSAccess();
test.GetMyInformation();
}
}
class WebServiceTest
{
private IGWS.IGWS SVC;
private String myAccessID;
private String myPassword;
private Dictionary<int, ErrorInfo> wsErrorCodes = new Dictionary<int,

ErrorInfo>();
/// <summary>
/// Get the client information from the Gateway
/// </summary>
public void GetMyInformation()
{
// Get all IsatData Pro Gateway Web Service error codes with descriptions
ErrorInfo[] errorInfos = SVC.InfoErrorInfos();
// Store error codes to a dictionary
if (errorInfos != null)
{
foreach (ErrorInfo errorInfo in errorInfos)
wsErrorCodes.Add(errorInfo.ID, errorInfo);
}
}
}
Figure 16 shows debugging information after the client calls the InfoErrorInfos web
service operation. It displays an array of received error information and details on one of
them.

Figure 16 Debug Information after InfoErrorInfos Call
Figure 17 provides a sample error message if the client calls a web service method with an
incorrect access ID or password.
Figure 17 Sample Error Message
If the client account has access to terminals from other IGWS accounts, the client can get
a list of these subaccounts and their terminals as displayed in the following code sample.
The following code sample also illustrates using dictionary of error codes (wsErrorCodes)
created by calling the InfoErrorInfos web service operation.

private Dictionary<String, SubaccountInfo> mySubaccounts =

new Dictionary<string, SubaccountInfo>();
/// <summary>
/// Get information about my subaccounts (if my account has any)
/// </summary>
public void GetSubaccountInformation()
{
// Get my subaccounts
GetSubaccountInfosResult subaccountResult = SVC.GetSubaccountInfos(myAccessID,
myPassword);
// Store subaccounts to a dictionary
if (subaccountResult != null && subaccountResult.ErrorID == 0)
{
if (subaccountResult.Subaccounts != null && subaccountResult.Subaccounts.Length > 0)
{
}
}
else if (subaccountResult != null)
{
Console.WriteLine("Error calling GetSubaccountInfos: [{0}]: {1} - {2}",
subaccountResult.ErrorID,
wsErrorCodes[subaccountResult.ErrorID].Name,
wsErrorCodes[subaccountResult.ErrorID].Description);
}
}
To send and/or retrieve messages related to these subaccounts, the client needs to provide
a subaccountID for each Submit/Get web service operation.
7.3 Submitting a To-Mobile Message

The following code sample shows several ways of sending to-mobile messages to the
terminals.
The first section of the code shows how to send multiple messages at once. Each of these
messages can have a different destination.
The second section of the code shows how to send a single message to many IsatData Pro
terminals in a single Send call.
/// <summary>
/// Sample code showing how to submit messages to the Gateway
/// </summary>
public void SubmitMessages()
{
//---------------------------------------------------------------------------
// SAMPLE 1 - send two different to-mobile messages to two different terminals
//---------------------------------------------------------------------------
// Create the messages

ForwardMessage []messages = new ForwardMessage[3];
// Message 1 ---------------------------------
// A simple binary message (reset - see [T203] for more details)
messages[0] = new ForwardMessage();

messages[0].DestinationID = "00300050SKY1A97";
messages[0].UserMessageID = 1;
messages[0].RawPayload = new byte[] { 0x00, 0x44, 0x00 };
// Message 2 ---------------------------------
// A simple customer specific message in a binary format. In case a customer defined
a message where SIN=128, MIN=1, and a content of 8 bytes, this would be
a way to send it in a binary form. The first byte is SIN, the second byte is MIN,
and the rest is its content.

messages[1].RawPayload = new byte[] { 0x80, 0x01, 0x01, 0x02, 0x03, 0x04, 0x05,
0x06, 0x07, 0x08};
// Message 3 ---------------------------------
// The reset message using common message format

messages[2].Payload = new Message();
messages[2].Payload.SIN = 0;
messages[2].Payload.MIN = 0x44;
messages[2].Payload.Fields = new Field[1];
messages[2].Payload.Fields[0] = new Field();
messages[2].Payload.Fields[0].Name = "resetType";
messages[2].Payload.Fields[0].Value = "ModemPreserve"
// Submit the client messages and check Gateway's response

SubmitMessagesResult submitResult = SVC.SubmitForwardMessages
(myAccessID, myPassword, messages);
if (submitResult != null && submitResult.ErrorID == 0)
{
if (submitResult.Submissions != null)
{
foreach (ForwardSubmission submissionInfo in submitResult.Submissions)
{
if (submissionInfo.ErrorID == 0)
{
Console.WriteLine("Message UserID={0} accepted, Gateway assigned ID:
{1}",
submissionInfo.UserMessageID,
submissionInfo.ForwardMessageID);
}
else
{
Console.WriteLine("Gateway rejected a message UserID={0}: [{1}]: {2} -
{3}",
submissionInfo.UserMessageID,
submissionInfo.ErrorID,
wsErrorCodes[submissionInfo.ErrorID].Name,
wsErrorCodes[submissionInfo.ErrorID].Description);
}
}

}
}
else if (submitResult != null)
{
Console.WriteLine("Error calling SubmitForwardMessages: [{0}]: {1} - {2}",
submitResult.ErrorID,
wsErrorCodes[submitResult.ErrorID].Name,
wsErrorCodes[submitResult.ErrorID].Description);
}
//---------------------------------------------------------------------------
// SAMPLE 2 - send one message to two different terminals
//---------------------------------------------------------------------------
// Create messages
ForwardMessage message = new ForwardMessage();
message.Payload = new Message();

message.Payload.SIN = 0;
message.Payload.MIN = 99;
message.Payload.Fields = new Field[1];
message.Payload.Fields[0] = new Field();
message.Payload.Fields[0].Name = "Period";
message.Payload.Fields[0].Value = "LastFullDay"
// Set the destination terminals

String[] terminals = {"00300050SKY1A97", "00200030SKY1A00"};
// Submit the messages and check Gateway's response

submitResult = SVC.SubmitForwardMessageToMultipleDestinations
(myAccessID, myPassword, message, terminals);
if (submitResult != null && submitResult.ErrorID == 0)
{
if (submitResult.Submissions != null)
{
foreach (ForwardSubmission submissionInfo in submitResult.Submissions)
{
if (submissionInfo.ErrorID == 0)
{
Console.WriteLine("Message for {0} accepted, Gateway assigned ID:
{1}",
submissionInfo.DestinationID,
submissionInfo.ForwardMessageID);
}
else
{
Console.WriteLine("Gateway rejected a message for {0}: [{1}]: {2} -
{3}",
submissionInfo.DestinationID,
submissionInfo.ErrorID,
wsErrorCodes[submissionInfo.ErrorID].Name,
wsErrorCodes[submissionInfo.ErrorID].Description);
}
}
}
}
else if (submitResult != null)
{

Console.WriteLine("Error calling SubmitForwardMessages: [{0}]: {1} - {2}",

submitResult.ErrorID,
wsErrorCodes[submitResult.ErrorID].Name,
wsErrorCodes[submitResult.ErrorID].Description);
}
}
Figure 18 displays debugging information after the client submits the messages.
Figure 18 Debug Information after Message Submission
After the client submits the messages it receives a result object back from the Gateway. Its
ErrorID field indicates if the web service call succeeded or not, and its Submissions
field contains information related to each to-mobile message.
Each ForwardSubmission record tells the client whether the Gateway has accepted the
message (ErrorID=0) or not (ErrorID>0). If the message has been accepted, the client gets
ForwardMessageID assigned to that message. If the client provided a UserMessageID,
it gets it back so it can pair this ID with the one generated by the Gateway.
7.4 Querying for a To-Mobile Message Status

After the client submits a message, if it is polling the IGWS regularly for new messages, it
gets both the from-mobile messages and updates of the submitted to-mobile messages.
If required, the client can also explicitly ask for a status of one or more submitted to-
mobile messages.
The following code sample queries status of two to-mobile messages.
/// <summary>
/// Sample code showing how to query status of a to-mobile message
/// </summary>
public void QueryFWMessageStatus()
{

// Set message IDs that Gateway has assigned to the client messages
ForwardStatusFilter filter = new ForwardStatusFilter();
// Important: Maximum number of message IDs in this array is 100.
Filter.ForwardMessageIDs = { 338882, 338884 };
// Note: You can also use a timestamp (StartUTC/EndUTC) as a high watermark when
querying message statuses. In that case you can get up to 500 statuses for each
GetForwardStatuses call (See section 4.1.3).
GetForwardStatusesResult result = SVC.GetForwardStatuses

(myAccessID, myPassword, filter);
if (result != null && result.ErrorID == 0)
{
foreach (ForwardStatus status in result.Statuses)
{
Console.WriteLine("Status of message ID={0}: {1}",
status.ForwardMessageID, status.State.ToString());
}
}
else if (result != null)
{
Console.WriteLine("Error calling GetForwardStatuses: [{0}]: {1} - {2}",
result.ErrorID,
wsErrorCodes[result.ErrorID].Name,
wsErrorCodes[result.ErrorID].Description);
}
}
Figure 19 displays debugging information after the client receives the status of a message.
Figure 19 Debug Information after Message Status

7.5 Polling for From-Mobile Messages Using a Timestamp as a

High Watermark
The best way to get all client messages from the IGWS is to regularly poll it. The client
server starts polling the Gateway using an initial query filter, and then the Gateway
provides filter updates needed to get new messages.
/// <summary>
/// Sample from-mobile message polling
/// </summary>
public void PollForReturnMessages()
{
// Get messages from the Gateway 10 times before returning
int numberOfPolls = 20;
int pollCounter = 0;
// Delay between two consecutive GetMessages calls. Your delay time

// would depend on the amount of traffic you expect.
int delayInSeconds = 20;
// Get current Gateway time

String startUTC = SVC.InfoUTC();
// Set the query filter

ReturnMessageFilter filter = new ReturnMessageFilter();
filter.StartUTC = startUTC; // Important: Update StartUTC based on a response
do
{
GetReturnMessagesResult result = SVC.GetReturnMessages(myAccessID, myPassword,
filter);
{
// Extract from-mobile messages
if (result.Messages != null && result.Messages.Length > 0)
{
Console.WriteLine("Return messages:");
foreach (ReturnMessage reMessage in result.Messages)
{
Console.WriteLine(" ID={0} SIN={1} Terminal={2}",
reMessage.ID, reMessage.SIN, reMessage.MobileID);
}
}
// Get filter values for the next poll. If no messages were returned,
// the 'NextStartUTC' will not be valid, i.e an empty string will be returned
if (!String.IsNullOrEmpty(result.NextStartUTC))
{
// Note: If you fail to update the StartUTC, your next GetReturnMessages
// call will return the same messages you already got.
filter.StartUTC = result.NextStartUTC;
}
else
{
Console.WriteLine("{0}: No new messages received",
DateTime.Now.ToString());
}
}

else if (result != null)

{
Console.WriteLine("Error calling GetReturnMessages: [{0}]: {1} - {2}",
result.ErrorID,
wsErrorCodes[result.ErrorID].Name,
wsErrorCodes[result.ErrorID].Description);
}
// Wait before polling the web service again!

System.Threading.Thread.Sleep(delayInSeconds * 1000);
} while (++pollCounter <= numberOfPolls);

}
}
In this sample, the client requests messages using the current Gateway UTC time. The
code polls the Gateway once every 20 seconds, 20 times.
Each time the client receives from-mobile messages and/or to-mobile message updates, it
also receives a NextStartUTC that represents the client's high watermark for getting
the latest messages.
Figure 20 displays debugging information if the client received some from-mobile
messages.
Figure 20 Debug Information for From-Mobile Messages
Figure 21 is the result of one cycle of Gateway polling.

Figure 21 Gateway Polling Result
7.6 Polling for From-Mobile Messages Using a Message ID as a

High Watermark
/// <summary>
/// Sample from-mobile message polling
/// </summary>
public void PollForReturnMessages()
{
// Get messages from the Gateway 20 times before returning
int numberOfPolls = 20;
int pollCounter = 0;
// Delay between two consecutive GetMessages calls. Your delay time

// would depend on the amount of traffic you expect.
int delayInSeconds = 20;
// Set the query filter

filter.StartMessageID = 2987645; // Important: Update based on a response
do
{
GetReturnMessagesResult result = SVC.GetReturnMessages(myAccessID, myPassword,
filter);
{
// Extract from-mobile messages
if (result.Messages != null && result.Messages.Length > 0)
{
Console.WriteLine("Return messages:");
foreach (ReturnMessage reMessage in result.Messages)
{
Console.WriteLine(" ID={0} SIN={1} Terminal={2}",
reMessage.ID, reMessage.SIN, reMessage.MobileID);
}
// Note: If you fail to update the StartMessageID, your next

// GetReturnMessages call will return the same messages you already got.

if (result.NextStartID > 0)
filter.StartMessageID = result.NextStartID;
}
}
// Wait before polling the web service again!

System.Threading.Thread.Sleep(delayInSeconds * 1000);
} while (++pollCounter <= numberOfPolls);

}
}

8 REST Web Service Interface

Samples can be found in the IDP Toolkit.
8.1 info_utc_time
Returns the current Gateway time. Equivalent to the SOAP web service operation,
InfoUTC().
Rate limited: No
Requires authentication: No
Response formats: json, xml
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_utc_time.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_utc_time.xml/
Parameters
None
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_utc_time
.json/
[
"2011-08-10 12:53:40"
]
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_utc_time
.xml/
<string>2011-08-22 18:10:45</string>

8.2 info_errors
Returns a list of all Gateway error codes with a description. Equivalent to SOAP web
service operation InfoErrorInfos().
Rate limited: No
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_errors.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_errors.xml/
Parameters
None
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_errors.js
on/
[
{
"ID": 17415,
"Name": "ERR_INVALID_BEAM",
"Description": "Invalid beam number"
},
{
"ID": 17668,
"Name": "ERR_INVALID_USER_OR_PASSWORD",
"Description": "Invalid user name or password"
},
{
"ID": 17697,
"Name": "ERR_INVALID_BROADCAST_ID_NOT_YOUR_ID",
"Description": "Invalid broadcast ID or the ID belongs to some other Gateway account"
},
{
"ID": 17698,
"Name": "ERR_RESTRICTED_MESSAGE",
"Description": "Sending of messages with this SIN and MIN pair is restricted."
},
…
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_errors.x
ml/
<ArrayOfErrorInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorInfo>
<ID>17415</ID>
<Name>ERR_INVALID_BEAM</Name>
<Description>Invalid beam number</Description>
</ErrorInfo>
<ErrorInfo>
<ID>17668</ID>

<Name>ERR_INVALID_USER_OR_PASSWORD</Name>
<Description>Invalid user name or password</Description>
</ErrorInfo>
<ErrorInfo>
<ID>17697</ID>
<Name>ERR_INVALID_BROADCAST_ID_NOT_YOUR_ID</Name>
<Description>
Invalid broadcast ID or the ID belongs to some other Gateway account
</Description>
</ErrorInfo>
<ErrorInfo>
<ID>17698</ID>
<Name>ERR_RESTRICTED_MESSAGE</Name>
<Description>
Sending of messages with this SIN and MIN pair is restricted.
</Description>
</ErrorInfo>
</ArrayOfErrorInfo>
…
8.3 info_version
Returns a Gateway version string. Equivalent to SOAP web service operation
InfoVersion().
Rate limited: No
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_version.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_version.xml/
Parameters
None
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_version.j
son/
"3.1.7.0"
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/info_version.x
ml/
<string>3.1.7.0</string>

8.4 get_subaccount_infos
Returns a list of subaccounts associated with the customer account. Equivalent to SOAP
web service operation GetSubaccountInfos().
Rate limited: Yes
Requires authentication: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_subaccount_infos.js
on/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_subaccount_infos.xm
l/
Parameters
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_subaccou
nt_infos.json/?access_id=70000352&password=KP0THGB6
{
"ErrorID": 0,
"Subaccounts": [
{
"AccountID": "60000012",
"Name": "TDM"
}
]
}
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_subaccou
nt_infos.xml/?access_id=70000352&password=KP0THGB6
<GetSubaccountInfosResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<ErrorID>0</ErrorID>
<Subaccounts>
<SubaccountInfo>
<AccountID>60000012</AccountID>
<Name>TDM</Name>
</SubaccountInfo>
</Subaccounts>
</GetSubaccountInfosResult>

8.5 get_broadcast_infos
Returns a list of broadcast ID information associated with the customer account or its sub-
account. Equivalent to SOAP web service operation GetBroadcastInfos() .
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_broadcast_infos.jso
n/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_broadcast_infos.xml
/
Parameters
subaccount_id (optional) Specify sub-account ID if you want to retrieve
broadcast ID information associated to that sub-account.
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_broadcast
_infos.json/?access_id=70000352&password=KP0THGB6
{
"ErrorID":0,
"BroadcastInfos":[
{"ID":"16777190GRP85BB","Description":"BC2"}
]
}
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_broadcast
_infos.xml/?access_ id=70000352&password=KP0THGB6
<GetBroadcastInfosResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<BroadcastInfos>
<BroadcastInfo>
<ID>16777190GRP85BB</ID>
<Description>BC2</Description>
</BroadcastInfo>
</BroadcastInfos>
</GetBroadcastInfosResult>

8.6 get_mobiles_paged
Returns a list of broadcast ID information associated with the customer account or its sub-
account. Equivalent to SOAP web service operation GetMobilesPaged().
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_mobiles_paged.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_mobiles_paged.xml/
Parameters
subaccount_id (optional) Specify sub-account ID if you want to retrieve
broadcast ID information associated to that sub-account.
since_mobile (optional) Starting terminal/mobile serial number
page_size (required) Page size - [1…1000]
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_mobiles_
paged.json/?access_id=70000352&password=KP0THGB6
{
"ErrorID":0,
"Mobiles":[
{"ID":"01000051SKY867C","Description":"Lan","LastRegistrationUTC":"2012-09-13
20:55:35","RegionName":"AMERRB16"},
{"ID":"01000057SKY9E9A","Description":"Rev2","LastRegistrationUTC":"2011-11-17
14:56:05","RegionName":"AMERRB16"},
{"ID":"01000064SKY3ABD","Description":"Test2","LastRegistrationUTC":"2011-11-03
14:35:52","RegionName":"AMERRB16"}
]
}
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_mobiles_
paged.xml/?access_id=70000352&password=KP0THGB6
<GetMobilesPagedResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<Mobiles>
<MobileExInfo>
<ID>01000039SKY5640</ID>
<Description>Test1</Description>
<LastRegistrationUTC>2011-06-30 13:22:17</LastRegistrationUTC>
<RegionName>EMEARB10</RegionName>
</MobileExInfo>
<MobileExInfo>

<ID>01000051SKY867C</ID>
<Description>Lan</Description>
<RegionName>AMERRB16</RegionName>
</MobileExInfo>
<MobileExInfo>
<ID>01000057SKY9E9A</ID>
<Description>Rev2</Description>
<RegionName>AMERRB16</RegionName>
</MobileExInfo>
</Mobiles>
</GetMobilesPagedResult>
8.7 get_return_messages
Returns array of from-mobile messages belonging to the customer account or one of its
subaccounts. Equivalent to SOAP web service operation GetReturnMessages().
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_return_messages.jso
n/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_return_messages.xml
/
Parameters
from_id (optional*) Set this value based on your previous response
(refer to the sample in section 7.6). If this field is specified,
the Gateway uses the message ID as a high watermark. It
returns messages that have arrived after the specified message.
If the field is present, start_utc andend_utc fields won't be
considered even if present.
Note: Either the from_id field or start_utc field must be present.
start_utc (optional*) Set this value based on your previous
response (refer to the sample in section 7.5). If this field
is specified, the Gateway returns messages that have
arrived after this timestamp.
end_utc (optional) If this field is specified, the Gateway returns
messages that have arrived between start_utc and end_utc
time
mobile_id (optional) Filters out all the messages except the ones
coming from this mobile ID

include_raw_payload (optional) If this field is specified and its value set to

true, the Gateway always returns messages' raw payload.
By default, this option is turned off, unless the Gateway
fails to decode the message, in which case the raw
payload is always returned.
sub_account_id (optional) If this field is specified, the Gateway returns
messages belonging to the subaccount
include_type (optional) Set this field to true if you want the Payload to
include the field types as well
include_subaccounts (optional) Set this field to true if you want to query
messages that belong to your account and all your
subaccounts. For this field to work, from_id parameter
has to be used instead of start_utc and end_utc field
Example Requests
Return all 70000001’s messages that have arrived after message with ID 1450235:
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_return_m
essages.xml/?access_id=70000352&password=KP0THGB6&from_id=1450235
Return all 70000001’s messages from-mobile 01000056SKY1A95 that have arrived after
message with ID 1450235:
essages.xml/?access_id=70000352&password=KP0THGB6&from_id=1450235&mobile_
id=01000056SKY1A95
Return all 70000001’s messages that have arrived after 3pm May 25, 2011, include raw
payload with all messages:
essages.xml/?access_id=70000352&password=KP0THGB6&start_utc=2011-05-
25%2015:00:00&include_raw_payload=true
Return all 70000001’s messages that have arrived between 3pm and 5:25pm on May 25,
2011:
essages.xml/?access_id=70000352&password=KP0THGB6&start_utc=2011-05-
25%2015:00:00&end_utc=2011-05-25%2017:25:00
<GetReturnMessagesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<More>true</More>
<NextStartUTC>2011-07-20 21:37:47</NextStartUTC>
<Messages>
<ReturnMessage>
<ID>940439</ID>
<MessageUTC>2011-06-29 03:01:17</MessageUTC>
<ReceiveUTC>2011-06-29 03:01:06</ReceiveUTC>
<SIN>0</SIN>
<MobileID>01000056SKY1A95</MobileID>
<RawPayload>AAEAUQ==</RawPayload>
<Payload Name="ReportBeamChange" SIN="0" MIN="1">

<Fields>
<Field Name="VirtualCarrier" Value="5"/>
<Field Name="Beam" Value="1"/>
</Fields>
</Payload>
<RegionName>EMEARB17</RegionName>
</ReturnMessage>
…
{
"ErrorID": 0,
"More": true,
"NextStartUTC": "2011-07-20 21:37:47",
"Messages": [
{
"ID": 940439,
"MessageUTC": "2011-06-29 03:01:17",
"ReceiveUTC": "2011-06-29 03:01:06",
"SIN": 0,
"MobileID": "01000056SKY1A95",
"RawPayload": [0, 1, 0, 81],
"Payload": {
"Name": "ReportBeamChange",
"SIN": 0,
"MIN": 1,
"Fields": [
{
"Name": "VirtualCarrier",
"Value": "5"
},
{
"Name": "Beam",
"Value": "1"
}
]
},
"RegionName": "EMEARB17"
}
]
}

8.8 get_forward_statuses
Returns statuses of sent forward (to-mobile) messages. Equivalent to SOAP web service
operation GetForwardStatuses().
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_statuses.js
on/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_statuses.xm
l/
Parameters
start_utc (optional*) If this field is specified, the Gateway returns
messages that have changed after this timestamp
*Note: Even though this and the fwIDs field is optional, one of
the two must be present
end_utc (optional) If this field is specified, the Gateway returns messages
that have changed between start_utc and end_utc time
fwIDs (optional*) List of comma separated forward message IDs whose
statuses are returned
sub_account_id (optional) If this field is specified, the Gateway returns messages
belonging to the subaccount
Example Requests
Return statuses of the messages with following IDs: 1450235,1450236
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
tatuses.xml/?access_id=70000352&password=KP0THGB6&fwIDs=1450235,1450236
Return statuses for all message changes that have happened after 3pm May 25, 2011:
tatuses.json/?access_id=70000352&password=KP0THGB6&start_utc=2011-05-
25%2015:00:00
{
"ErrorID": 0,
"More": true,
"NextStartUTC": "2011-07-22 14:23:02",
"Statuses": [
{
"ForwardMessageID": 964363,
"IsClosed": true,
"State": 1,
"ErrorID": 0,

"StateUTC": "2011-06-29 13:44:25",

"ReferenceNumber": 1030
},
{
"IsClosed": true,
"State": 1,
"ErrorID": 0,
"StateUTC": "2011-06-29 14:15:50",
}
]
}
tatuses.xml/?access_id=70000352&password=KP0THGB6&start_utc=2011-05-
25%2015:00:00
<GetForwardStatusesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<More>true</More>
<NextStartUTC>2011-07-22 14:23:02</NextStartUTC>
<Statuses>
<ForwardStatus>
<ForwardMessageID>964363</ForwardMessageID>
<IsClosed>true</IsClosed>
<State>RECEIVED</State>
<StateUTC>2011-06-29 13:44:25</StateUTC>
<ReferenceNumber>1030</ReferenceNumber>
</ForwardStatus>
<ForwardStatus>
<State>DELIVERY_FAILED</State>
</ForwardStatus>
…

8.9 get_forward_messages
Returns contents of forward messages. Equivalent to SOAP web service operation
GetForwardMessages().
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_messages.js
on/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_messages.xm
l/
Parameters
fwIDs (required) List of comma separated forward message IDs whose
content is returned
sub_account_id (optional) If this field is specified, the Gateway returns the status
of messages associated with the subaccount
Example Requests
Return messages with following IDs: 1153034,1151791
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_
messages.json/?access_id=70000352&password=KP0THGB6&fwIDs=1153034,1151791
{
"ErrorID": 0,
"Messages": [
{
"ID": 1153034,
"StatusUTC": "2011-08-04 20:38:34",
"CreateUTC": "2011-08-04 20:38:26",
"IsClosed": true,
"State": 1,
"DestinationID": "01000056SKY1A95",
"ErrorID": 0,
"RawPayload": [23,5,0],
"Payload": {
"Name": "getDataLogEntries",
"SIN": 23,
"MIN": 5,
"IsForward": "True"
},
},
{
"ID": 1151791,
"StatusUTC": "2011-08-04 16:02:35",
"CreateUTC": "2011-08-04 15:47:55",

"IsClosed": true,
"State": 1,
"DestinationID": "16777178GRP557F",
"ErrorID": 0,
"RawPayload": [0,98],
"Payload": {
"Name": "RequestLastRxMetrics",
"SIN": 0,
"MIN": 98,
"IsForward": "True"
},
}
]
}
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_
messages.xml/?access_id=70000352&password=KP0THGB6&fwIDs=1153034,1151791
<GetForwardMessagesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<Messages>
<ForwardMessageRecord>
<ID>1153034</ID>
<StatusUTC>2011-08-04 20:38:34</StatusUTC>
<CreateUTC>2011-08-04 20:38:26</CreateUTC>
<DestinationID>01000056SKY1A95</DestinationID>
<RawPayload>FwUA</RawPayload>
<Payload Name="getDataLogEntries" SIN="23" MIN="5" IsForward="True"/>
</ForwardMessageRecord>
<ForwardMessageRecord>
<ID>1151791</ID>
<StatusUTC>2011-08-04 16:02:35</StatusUTC>
<CreateUTC>2011-08-04 15:47:55</CreateUTC>
<DestinationID>16777178GRP557F</DestinationID>
<RawPayload>AGI=</RawPayload>
<Payload Name="RequestLastRxMetrics" SIN="0" MIN="98" IsForward="True"/>
</ForwardMessageRecord>
</Messages>
</GetForwardMessagesResult>

8.10 submit_messages
Submits multiple messages to their destinations. Equivalent to SOAP web service
operation SubmitForwardMessages().
Rate limited: Yes
HTTP methods: POST
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages.xml/
Parameters
messages (required) Array of ForwardMessage objects
Example Requests
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messa
ges.json/
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages.json/
HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: 172.20.101.174
Content-Length: 134
Expect: 100-continue
Connection: Keep-Alive
{
"accessID": "70000001",
"password": "password",
"messages": [
{
"UserMessageID": 101,
"RawPayload": [16,1]
}
]
}
Response
{
"SubmitForwardMessages_JResult": {
"ErrorID": 0,
"Submissions": [
{

"StateUTC": "2011-08-23 17:24:05",
"ErrorID": 0,
"UserMessageID": 101
}
]
}
}
POST
ges.xml/
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages.xml/
HTTP/1.1
Content-Type: application/xml; charset=utf-8
Host: 172.20.101.174
Content-Length: 450
<?xml version="1.0" encoding="utf-8"?>

<SubmitForwardMessages xmlns="IGWS" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<accessID>70000006</accessID>
<password>password</password>
<messages>
<ForwardMessage>
<RawPayload>EAE=</RawPayload>
<UserMessageID>101</UserMessageID>
</ForwardMessage>
</messages>
</SubmitForwardMessages>
Response

<SubmitForwardMessagesResponse xmlns="IGWS" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SubmitForwardMessagesResult>
<Submissions>
<ForwardSubmission>
</ForwardSubmission>
</Submissions>
</SubmitForwardMessagesResult>
</SubmitForwardMessagesResponse>

8.11 submit_messages_to_destinations
Submits a message to multiple destinations. Equivalent to SOAP web service operation
SubmitForwardMessageToMultipleDestinations().
Rate limited: Yes
HTTP methods: POST
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages_to_dest
inations.json/
inations.xml/
Parameters
destinations (required) A list of coma separated destinations the message
needs to be sent to
message (required) A ForwardMessage object
Example Requests
POST
ges_to_destinations.json/
POST
inations.json/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: 172.20.101.174
Content-Length: 165
{
"accessID": "70000001",
"password": "password",
"destinations": "01000056SKY1A95,01000056SKY1A95",
"message": {
"DestinationID": "",
"UserMessageID": 0,
"RawPayload": [16,1]
}
}

Response
{
"ErrorID": 0,
"Submissions": [
{
"StateUTC": "2011-08-23 18:12:21",
"ErrorID": 0,
"UserMessageID": 0
},
{
"StateUTC": "2011-08-23 18:12:21",
"ErrorID": 0,
"UserMessageID": 0
}
]
}
POST
ges_to_destinations.xml/
POST
inations.xml/ HTTP/1.1
Content-Type: application/xml; charset=utf-8
Host: ott-svrbaskilap.skywavemobile.com
Content-Length: 410
<SubmitForwardMessageToMultipleDestinations xmlns="IGWS">
<accessID>70000006</accessID>
<password>password</password>
<destinations>01000056SKY1A95,01000056SKY1A95</destinations>
<message xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DestinationID i:nil="true" xmlns=""/>
<UserMessageID xmlns="">0</UserMessageID>
<RawPayload xmlns="">EAE=</RawPayload>
</message>
</SubmitForwardMessageToMultipleDestinations>

Response

<SubmitMessagesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<Submissions>
<ForwardSubmission>
<ForwardSubmission>
</Submissions>
</SubmitMessagesResult>
8.12 submit_cancelations
Submits cancellation request for specified messages. Equivalent to SOAP web service
operation SubmitMessageCancelations() (Section 4.3.3).
Rate limited: Yes
HTTP methods: GET
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_cancelations.jso
n/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_cancelations.xml
/
Parameters
fwIDs (required) List of comma separated IDs of messages that need to
be cancelled
Example Requests
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_cancel
ations.xml/?access_id=70000352&password=KP0THGB6&fwIDs=1209992

{
"ErrorID": 0,
"Submissions": [
{
"ForwardMessageID": -1,
"DestinationID": "",
"StateUTC": "",
"ErrorID": 115,
"UserMessageID": 0
}
]
}
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_cancel
ations.xml/?access_id=70000352&password=KP0THGB6&fwIDs=1209992

<SubmitMessagesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<Submissions>
<ForwardSubmission>
<ForwardMessageID>-1</ForwardMessageID>
<DestinationID/>
<StateUTC/>
</Submissions>
</SubmitMessagesResult>

9 Tutorial – SOAP Based Web Service

9.1 Getting Started
 Contact SkyWave Customer Support to obtain the client service URL, access ID and
password.
For all non-information based web service operations, users need to supply their
access ID and a password. The IsatData Pro Gateway Web Service is a stateless
service - no user state is maintained between two web service calls.
 Obtain the web service's WSDL file.
If the URL received from SkyWave Customer Support is
http://isatdatapro.skywave.com/GLGW/GWS ervices_v1/Messages.svc, use
http://isatdatapro.skywave.com/GLGW/GWServices_v1/Messages.wsdl
to access the WSDL file. This file allows the software development tools to create
proxy classes used to access the web service.
The client can store these errors in a hash table for a quick retrieval of the error
information.
9.2 Required Materials and Equipment

For illustration purposes only, this tutorial uses the materials and equipment listed below
which you require in order to work through the examples in this section. There are other
software tools you can use to achieve the same results.
 Activated IDP terminals
 PC with Microsoft Windows XP® SP2, Windows Vista®, or Windows® 7 installed
 Internet connectivity
 Microsoft® NET Framework version 3.5 SP1 or higher (support.microsoft.com)
 Microsoft® Visual Studio®
9.3 Creating and Configuring a New Project

Note: Visual Studio® is a Microsoft product therefore, some aspects of the user
interface may change in future product releases. The screen shots in this
document may not match the appearance of the Visual Studio desktop of
the release you are using. Only the basic steps required for this tutorial are
described in this document. Please refer to the Microsoft website for
documentation and troubleshooting on all Microsoft products.
Before using the IsatData Pro Gateway Web Service, you need to create a project
workspace.
1. Launch Visual Studio from your PC in order to create a new Visual Studio console
application project (Figure 22).
2. Name your project “TestSamples” and click OK.

Figure 22 New Visual Studio Project
3. Select Add Service Reference from the Solution's Context menu to add the IsatData
Pro Gateway Web Service (IGWS) as a web reference to your project.
4. Click Advanced (see
5. Figure 23). The Service Reference Settings window appears.
Figure 23 Add a Service Reference

6. Click Add Web Reference (see Figure 24).

Figure 24 Service Reference Settings
7. Type the URL of the WSDL file you saved to your disk earlier or the URL of the web
site (see Figure 25).
Figure 25 Enter the URL
Sample name –
you can type any
name here
8. Click Go to add a web reference name (see Figure 25).

9. Type "IGWS" (or the reference name you used above), this is the web reference name
used in this tutorial (see Figure 25), and click Add Reference.
Visual Studio creates all the necessary files and adds them to your project.
Figure 26 IGWS Sample Code
A Web reference is a generated proxy class that locally represents the exposed
functionality of an XML web service. The proxy class defines methods that represent the
actual methods exposed by an XML web service. When the client application creates an
instance of the proxy class, the application can call the XML web service methods as if
the XML web service were a locally available component.
Code samples can now be added and complied. Refer to APPENDIX D for code
description details.

APPENDIX A Common IGWS Error Codes

The following table lists common IGWS error codes. To see a complete list of IGWS
error codes use the web service operation InfoErrorInfos (refer to section 4.2.1).
Name ID Description
ERR_INVALID_MESSAGE_CONTENT 3 Customer has submitted an invalid message.
ERR_MT_SN_MISSING 4 Terminal serial number is missing from the message.
The Gateway does not know where to send the
message.
ERR_INVALID_MESSAGE_ID 14 A customer has specified an invalid message ID, or
required message IDs are missing. This error could
happen if the requested message is too old and is no
longer in our system.
ERR_CUSTOMER_DELAYED 16 Customer is accessing the web service too often. For
every customer account, there is a limit in number of
GET and SEND (20 by default) web service accesses
for a unit of time (10 seconds by default). For
example, if a customer tries to query messages more
than 20 times in a 10 second interval, web service
responds with this error code.
ERR_INVALID_INPUT_PARAMETER_TIMESTAMP_FORMAT 17 A timestamp parameter of a web service operation is
not in a correct form.
ERR_GATEWAY_NOT_READY 20 Gateway web service is currently not in an
operational state.
ERR_INVALID_INPUT_DATA 23 One of the web service parameters is not correct (for
example – array of message IDs is empty when
calling GetFWMessages web service operation)
ERR_INVALID_CUSTOMER_GW_VAR_ID 40 This error happens only if the terminal is not
provisioned correctly on the Gateway.
ERR_INVALID_MT_SN_LENGTH 50 Terminal serial number is invalid (wrong length)
ERR_UNAUTHORIZED_FOR_THIS_OPERATION 104 Customer account is not authorized for the web
service operation. For example, a customer has not
been provisioned as a super account, but they tried to
send a message as if they were.
ERR_UNABLE_TO_CANCEL_THE_MESSAGE 115 Web service was not able to cancel a to-mobile
message.
ERR_INVALID_MESSAGE_XML_CONTENT 116 Format of a common message is invalid or cannot be
encoded. This error also happens if the customer
hasn’t uploaded their custom message definition
through the Versa Admin provisioning site.
ERR_INTERNAL_EXCEPTION 128 Internal Gateway error – please report to customer
support.
ERR_INVALID_TERMINAL_ID_NO_SUCH_TERMINAL 513 Gateway was unable to find information related to the
specified terminal. Invalid mobile ID specified or a
provisioning issue.
ERR_INVALID_TERMINAL_ID_NOT_YOUR_TERMINAL 514 The specified terminal does not belong to a Gateway
account trying to use it.
ERR_TERMINAL_NOT_REGISTERED 516 The terminal has not been registered yet. Gateway is
unable to send the message to it.
ERR_INVALID_BROADCAST_ID_NO_SUCH_ID 12310 A customer has specified an invalid broadcast ID.
ERR_TERMINAL_IS_DISABLED 12311 Specified terminal was disabled. Messages cannot be
submitted to it.

Name ID Description
ERR_BROADCAST_ID_IS_DISABLED 12312 Specified broadcast ID was disabled. Messages
cannot be broadcast to it.
ERR_MESSAGE_ACK_ERROR_CONNECTION_LOSS 17686 The to-mobile message has closed due to connection
loss.
ERR_AUTHENTICATION_ERROR 21785 Customer authentication failed (invalid credentials or
customer not provisioned).
ERR_INVALID_WS_PARAMETER 21786 One of parameters used in the web service operation
call is not valid.
ERR_INVALID_BROADCAST_ID_NOT_YOUR_ID 21793 The specified broadcast ID does not belong to the
Gateway account trying to use it.
ERR_RESTRICTED_MESSAGE 21794 Customer is restricted from sending messages of this
type.
ERR_REGULAR_MESSAGE_SIZE_QUEUE_FULL 21795 Message queue for regular sized (less than 5000
bytes) messages for the specified terminal is full.
ERR_LARGE_MESSAGE_SIZE_QUEUE_FULL 21796 Message queue for large sized (more than 5000
bytes) messages for the specified terminal is full.
ERR_LOW_POWER_MODE_MESSAGE_TOO_LONG 21797 Message for a low power mode terminal is too long
(more than 5000 bytes).
To-Mobile Message Failure Error Codes

The following error codes relate to to-mobile message states when the message failed to
be delivered.
Name ID Description
ERR_NDN_INVALID_BEAM 12308 To-mobile message failed to be delivered to the
terminal.
Reason: Invalid beam number.
ERR_NDN_TIMED_OUT 12309 To-mobile message failed to be delivered to the
terminal.
Reason: Message timed out.
ERR_NDN_INVALID_PRIORITY 21791 To-mobile message failed to be delivered to the
terminal.
Reason: Invalid priority.
ERR_NDN_FAILED_CURRENT_BEAM_UPDATE 21787 To-mobile message failed to be delivered to the
terminal.
Reason: Failed to update the current beam
number.
ERR_MESSAGE_TOO_LONG 17678 To-mobile message failed to be delivered to the
terminal.
Reason: Message is too big.
ERR_NDN_TOO_MANY_MESSAGES 21788 To-mobile message failed to be delivered to the
terminal.
Reason: Too many messages.
ERR_NDN_INITIAL_SYSTEM_STATE 21789 To-mobile message failed to be delivered to the
terminal.
Reason: Initial system state.
ERR_NDN_TERMINAL_WAS_RESET 21792 To-mobile message failed to be delivered to the
terminal.
Reason: Terminal was reset.
ERR_NDN_MAX_RETRY_EXHAUSTED 21809 To-mobile message failed to be delivered to the
terminal.
Reason: Maximum retry/overflow of first
packet of low-power messages exhausted.

Name ID Description
ERR_NDN_INVALID_MODEM_WI 21810 To-mobile message failed to be delivered to the
terminal.
Reason: Invalid modem wake-up interval
ERR_NDN_FAILED_TO_LOAD 21811 Failed to load the message from the database.
ERR_NDN_TIMEOUT_NO_CHANCE_TO_TRANSMIT 21812 Message timeout–never had chance to be
transmitted.
ERR_NDN_TIMEOUT_SOME_ATTEMPTS_TO_TRANSMIT 21813 Message timeout–some attempts made but
never received modem’s ACK, and later had no
chance to be transmitted.
ERR_NDN_TIMEOUT_SOME_ATTEMPTS_TO_TRANSMIT_ACKED 21814 Message timeout–some successful attempts
made, modem’s ACK received, but later no
chance to be transmitted.
ERR_NDN_TERMINAL_RESET_NO_CHANCE_TO_TRANSMIT 21815 Terminal was reset–never had chance to be
transmitted.
ERR_NDN_TERMINAL_RESET_SOME_ATTEMPTS_TO_TRANSMIT 21816 Terminal was reset–some attempts made but
never received modem’s ACK.

APPENDIX B Interface Test System

Overview
SkyWave now provides test portals corresponding to all of the major traffic and
administrative enterprise to enterprise (e2e) interfaces.
This section outlines the necessary connection parameters for the IsatData Pro (IGWS)
Gateway.
SkyWave's intent is that this test interface is always available for your back-office
development testing, and SkyWave endeavors to roll out new network interface software
on this portal one month prior to roll out on the associated network servers.
IGWS
Access ID: 70000934
Password: password
GET/SEND 0 - unlimited
web service call
frequency
limits:
Mobile ID: 01097623SKY2C68
External http://isatdatapro.swlab.ca:8001/GLGW/GWServices_v1/Messages.svc
URLs: https://isatdatapro.swlab.ca:8143/GLGW/GWServices_v1/Messages.svc
All messages sent to the terminal are immediately acknowledged by a mobile simulator.

APPENDIX C Web Service Client Development Best

Practices
WSDL File
Use the WSDL file to generate proxy classes when accessing the IsatData Pro Web
Service through the SOAP interface.
SkyWave recommends setting the web service's URL to the one provided instead of
relying on a web service URL within the WSDL file itself.
Note: The WSDL file should be used during the development stage only.
Receiving Sent To-mobile Messages

If you send a small number of to-mobile messages (less than 10 per minute), you can
query their status by providing their forward message IDs:
SOAP:
filter.ForwardMessageIDs = { 338882, 338884 }; // Maximum number of IDs in this array is
100.
GetForwardStatusesResult result = SVC.GetForwardStatuses(myAccessID, myPassword, filter);
REST:
tatuses.xml/?access_id=70000999&password=0X0X0GB6&fwIDs=338882,338884
OR,
tatuses.json/?access_id=70000999&password=0X0X0GB6&fwIDs=338882,338884
If you send a large amount of to-mobile messages (more than 10 per minute) you can use
a time stamp as a high watermark. This allows you to receive up to 500 statuses with each
web service call.
Note: SkyWave recommends using UTC time instead of your local time for time
stamps.
SOAP:
// Give me statuses for all to-mobile messages whose statuses have changed
since
// Sep. 25, 2013 15:00:20 UTC
filter.StartUTC = "2013-09-25 15:00:20";
do
{
GetForwardStatusesResult result = SVC.GetForwardStatuses(myAccessID,
myPassword, filter);
if (result != null && result.ErrorID == 0 && result.Statuses != null &&
result.Statuses.Length > 0)
{
processStatuses(result.Statuses); // We got back some statuses,
process them

filter.StartUTC = result.NextStartUTC; // Important! Don't forget to

update your high watermark.
}
Sleep(20 * 1000); // Wait 20 seconds between each GetForwardStatuses call
// The actual delay time will depend on the amount of traffic you expect
// and limits imposed over your account.
} while (!done);
REST:
tatuses.xml/?access_id=70000999&password=0X0X0GB6&start_utc=2013-09-
25%2015:00:20
OR,
tatuses.json/?access_id=70000999&password=0X0X0GB6&start_utc=2013-09-
25%2015:00:20
Note: It is important to update your high watermark when you receive statuses.
Failure to do so causes you to receive the same statuses and after 500 there
is no guarantee that you are receiving the most recent.
Receiving From-Mobile Messages

The most efficient way to receive from-mobile messages is to use the message ID as a
high watermark.
SOAP:
filter.StartMessageID = 2987645;
do
{
GetReturnMessagesResult result = null;
try {
result = SVC.GetReturnMessages(myAccessID, myPassword, filter);
}
catch(Exception wsCallException)
{
// Process web service call exception (network issues, …)
}
if (result != null && result.ErrorID == 0 && result.Messages != null &&
result.Messages.Length > 0)
{
processFromMobileMessages(result.Messages); // We got back some
messages, process them
// Important! Don't forget to update your high watermark.
}
Sleep(20 * 1000); // Wait 20 seconds between each GetReturnMessages call
// The actual delay time will depend on the amount of traffic you expect
// and limits imposed over your account.
} while (!done);

REST:
essages.xml/?access_id=70000111&password=K101H1B1&from_id=2987645
OR,
essages.json/?access_id=70000111&password=K101H1B1&from_id=2987645
Note: It is important to update your high watermark when you receive messages.
Failure to do so causes you to receive the same set of messages and after
500 there is no guarantee that you are receiving the most recent ones.
Frequency of Web Service Calls

The frequency of your web service calls depends on the number of messages you send
and receive. The number of to-mobile messages is usually smaller than the number of
from-mobile messages, so the frequency of your GetForwardStatuses calls can be lower
than the frequency of your GetReturnMessages calls.
Each of these calls can provide up to 500 messages/message statuses. If you call
GetReturnMessages once every 30 seconds, and you receive 500 messages, you can call
again immediately with an updated high watermark to get any remaining new messages.
The maximum rate, by default is 20 calls within a 10 second interval.
int sleepInMilliseconds = 30 * 1000;
int ERR_CUSTOMER_DELAYED = 16;

filter.StartMessageID = 2987645;
do
{
GetReturnMessagesResult result = null;
try {
result = SVC.GetReturnMessages(myAccessID, myPassword, filter);
}
catch(Exception wsCallException)
{
// Process web service call exception (network issues, …)
}
if (result != null && result.ErrorID == 0 && result.Messages != null &&
result.Messages.Length > 0)
{
processFromMobileMessages(result.Messages); // We got back some
messages, process them
// Important! Don't forget to update your high watermark.
if (result.Messages.Length >= 500)
{
// We got back maximum number of from-mobile messages. More
messages are probably still there.
// Try to get them immediately
sleepInMilliseconds = 0;
}
else
{
// Get back to the usual sleep time

sleepInMilliseconds = 30 * 1000;
}
}
else if (result != null && result.ErrorID == ERR_CUSTOMER_DELAYED)
{
// Calling the web service too often - Extend the sleep time again.
}
if(sleepInMilliseconds > 0)
Sleep(sleepInMilliseconds);
} while (!done);
// Calling the web service too often - Extend the sleep time again.
}
if(sleepInMilliseconds > 0)
Sleep(sleepInMilliseconds);
} while (!done);

APPENDIX D Interface Code Description

This section provides an overview of the IsatData Pro Gateway Web Service's (IGWS)
sample client application code.
Sample code provided with the IDP Toolkit contains C# and Java samples that interface
with the IsatData Pro Gateway Web Service (IGWS) SOAP interface.
After installing the IDP Toolkit using the default installation path, the following
compressed sample code can be found in Program Files\SkyWave\IDP
Toolkit\Gateway folder:
 C# SOAP Sample.zip - Compressed C#/.NET sample code
 Java Sample.zip - Compressed Java sample code
C# .NET SOAP Client Sample

The C# sample code can be extracted from the C# SOAP Sample.zip file. It shows
developers how to:
 Initialize the IGWS client
 Get account information
 Submit to-mobile messages
 Poll the web service for from-mobile messages
 Poll the web service for to-mobile message status updates
Requirements
The following tools are required to develop a client sample:
 Installed Microsoft .NET Framework 3.5 and Visual Studio 2008 or higher.
 Valid IsatData Pro Gateway account
Getting Started
Before you can connect to the IGWS you need to update the Program.cs file with your
account information:
 AccessID field of the WebServiceAccount:
Set it to your IGWS account's access ID
 Password field of the WebServiceAccount:
Set it to your IGWS account's password
 MobileID1 field of the WebServiceAccount:
Enter a valid mobile ID from your IGWS account.
 MobileID2 field of the WebServiceAccount:

Java SOAP Client Sample

The Java sample code can be extracted from the Java Sample.zip file. It shows developers
how to:
 Generate Java proxy classes from the web service's WSDL file
 Initialize the IGWS client
 Get account information
 Submit to-mobile messages
 Poll the web service for from-mobile messages
 Poll the web service for to-mobile message status updates
Requirements
The following tools are required to develop a client sample:
 Installed Java SDK 1.6.25
 Valid IDP Gateway account
Getting Started
Update all relevant paths in all the .bat files and then update the Main.java file with your
account information:
 accessID field:
Set it to your IGWS account's access ID
 password:
Set it to your IGWS account's password
 mobileID:
Generating IGWS Proxy Classes

To update generated Java IGWS proxy classes, run CreateProxy.bat. It executes standard
Java SDK's wsimport utility.

Acronyms/Glossary
Broadcast ID A broadcast ID is globally unique and follows the numbering
scheme NNNNNNNNGRPXXXX, where NNNNNNNN is a
number assigned by SkyWave.
Forward message A message sent to the terminal. Often referred to as a to-mobile
message.
GPS Global Positioning System. A satellite-based system that allows the
terminal to determine the longitude and latitude (and hence the
location) of a monitored asset such as a truck or a ship.
IGWS IsatData Pro Gateway Web Service
I/O input/output
mobile ID A single identification sequence that appears on the terminal as
NNNNNNNNSKYXXXX, where NNNNNNNN is a number
assigned by SkyWave.
OTA over-the-air
Polling A poll is an information request sent to the terminal from the client
application. The poll may be a request for GPS position or for the
state of the terminal’s I/O (input/output) ports, or both. Polling is
always driven by the user’s application.
Return message A message sent from a terminal. Often referred to as a from-mobile
message.
Rx receive
SOAP Simple Object Access Protocol
Subaccounts Other users Gateway terminal accounts to which the client has
access.
Tx transmit
UTC Coordinated Universal Time - All timestamps exchanged between
the client and the Gateway use the following format:
YYYY-MM-DD hh:mm:ss
WSDL Web Services Description Language

Revision History
Version Date Details
10 Aug 2014 See What's New? section for details
09 Feb 2014 Changed to-mobile message billing rule; Added web service updates
notes; Updated Get Classes figure and To-Mobile Message Related
Classes figure; Added OTAMessageSize field to Return Message Class;
Added include_subaccounts parameter to get_return_messages; Added
ERR_MESSAGE_ACK_ERROR_CONNECTION_LOSS error code;
Added ID number for
ERR_INVALID_BROADCAST_ID_NOT_YOUR_ID; Incorporated
content of obsolete [N202]; Minor updates and edits throughout.
08 Sept 2013 Added note about maximum number of message IDs and using
timestamp to ForwardStatusFilter code; Added notes about delay time
dependency and updating to GetReturnMessages code; Updated
delayInSeconds values for GetMessages calls; Updated number of times
a Gateway gets messages before returning; Added information on setting
the form_id and start_utc values; Changed message acknowledgement
simulator to mobile simulator; Added APPENDIX C.
07 May 2013 Added new wake-up intervals for ultra-low power; Added Get
operations: GetBroadcastInfos, GetMobilesPaged; Updated description
for Get Classes: StartUTC, EndUTC, and SubAccountID; Added new
Get Classes: IncludeAllsubaccounts, IncludeAllSubaccountsSpecified,
IncludeType and IncludeTypeSpecified; Added new Submission Class:
OTAMessageSize; Added information about polling the web service
using a high watermark; Updated REST Web Service Interface section
and http links; Added interface test system details.
06 Mar 2013 See 07.
5.02 Nov 2012 Limited customer release.
05 Oct 2012 See 07.
04.02 Jun 2012 References to account ID changed to access ID where necessary.
References to subaccount_id changed to sub_account_id where
necessary.
04.01 May 2012 Limited customer release.
04 Dec 2011 Updated GetForwardStatuses, Updated SubmitForwardMessages ,
Added details about common message fields and a common message
example, Updated sample code for submitting a to-mobile message,
Minor updates throughout
03 Nov 2011 Updates for firmware release 1.1.0 which supports low power operation.
Added details about support for low power mobile devices, Added
information about submitting a message to low power mobile devices
and message timeout details, Added TerminalWakeupPeriod and
ScheduledSendUTC to Submission Classes
02 Sep 2011 Added information about creating and uploading a message definition
file, Changed the maximum message size for GetForwardStatuses and
GetReturnMessages to 500, Updated the information operations
description, Updated the submit operations description, size of to-mobile
messages and listed possible error codes, Deleted the waiting message
state, Added StartMessageID and NextStartID to Get Classes, Added
TerminalWakeupPeriod and ScheduledSendUTC to Submission Classes,
Removed JAVA examples
01 Aug 2011 Official customer release
.11 Feb 2011 Limited customer release
.14 Apr 2011 Limited customer release

www.SkyWave.com

N201 V10 IsatData Pro Gateway Web Service Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

N201 V10 IsatData Pro Gateway Web Service Guide

Încărcat de

Drepturi de autor:

Formate disponibile

IsatData Pro Gateway Web Service (IGWS)

The electronic version of this document allows

© SkyWave Mobile Communications Inc.

N201, Version 10 ii © SkyWave Proprietary

© SkyWave Proprietary iii N201, Version 10

6.1 Get Classes ....................................................................................................................... 19

N201, Version 10 iv © SkyWave Proprietary

© SkyWave Proprietary v N201, Version 10

THIS PAGE INTENTIONALLY LEFT BLANK

N201, Version 10 vi © SkyWave Proprietary

© SkyWave Proprietary vii N201, Version 10

[N200] IsatData Pro Network Services Overview

N201, Version 10 viii © SkyWave Proprietary

SkyWave Proprietary 1 N201, Version 10

IsatData Pro Gateway

End user applications IGWS

AccessID: 60001 Mobile 1

Gateway account Mobile 2

N201, Version 10 2 © SkyWave Proprietary

2.1.1 Low Power Mode

2.2 Gateway Accounts

SkyWave Proprietary 3 N201, Version 10

A subaccount is a separate Gateway account (Figure 5) that a Gateway customer can

N201, Version 10 4 © SkyWave Proprietary

Figure 5 Subaccounts Relationship

Subaccount IDs Mobile IDs

SkyWave Proprietary 5 N201, Version 10

3 The IGWS Protocol

Client Application IGWS

N201, Version 10 6 © SkyWave Proprietary

3.1 Submitting Messages

3.1.1 Submitting Messages to Terminals in Low Power Mode

3.1.2 Message Timeout

SkyWave Proprietary 7 N201, Version 10

Figure 7 Submitting Messages

Client application Gateway web service

SubmitForwardMessage(accessID, password, message, UserMessageID)

Checks the message destination

Verifies the message content

Sends the message out

Check for errors

3.2 Getting Your Messages

N201, Version 10 8 © SkyWave Proprietary

Client application Gateway web service

GetReturnMessages(accessID, password, high watermark)

Check for errors

GetReturnMessages(accessID, password, high watermark)

Messages, error ID, next high watermark...

Check for errors

GetReturnMessages(accessID, password, high watermark)

Messages, error ID, next high watermark...

3.2.1 Message Retention

SkyWave Proprietary 9 N201, Version 10

4 Web Service Application Programming Interface

4.1 Get Operations

N201, Version 10 10 © SkyWave Proprietary

SkyWave Proprietary 11 N201, Version 10

4.2 Information Operations

4.3 Submit Operations

N201, Version 10 12 © SkyWave Proprietary

Open states Closed states

A message has one of the following states:

SkyWave Proprietary 13 N201, Version 10

N201, Version 10 14 © SkyWave Proprietary