Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
User Guide
N201, Version 10
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
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
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
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.
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
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
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
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.
More details on the System messages to configure the wake-up interval can be found in
[T203].
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
Mobile IDs
Access ID/password
Access limits
Account information
Broadcast IDs
Gateway account
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.
SubmitForwardMessage()
SubmitMessagesResult
GetReturnMessages()
GetReturnMessagesResult
GetReturnMessages()
GetReturnMessagesResult
SubmitForwardMessage()
SubmitMessagesResult
GetReturnMessages()
GetReturnMessagesResult
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.
Checks credentials
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
Checks credentials
Retrieve messages
Messages, error ID, next high watermark...
Store messages
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.
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.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();
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
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".
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.
<Element Index="0">
<Fields>
<Field Name="Email" Value="me@me.com" />
<Field Name="Subject" Value="subject" />
</Fields>
</Element>
</Elements>
</Field >
</Fields>
</Message>
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.
6 Classes
This section lists all the class definitions for the get, set, and information operations.
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).
This field is not processed if the field IncludeAllSubacounts
is included and set to true.
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.
This field is not processed if the field IncludeAllSubacounts
is included and set to true.
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.
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)
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
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
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.
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;
// 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";
}
}
}
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;
/// <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 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.
/// <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.
/// <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
//---------------------------------------------------------------------------
// Message 1 ---------------------------------
// A simple binary message (reset - see [T203] for more details)
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.
// Message 3 ---------------------------------
// The reset message using common message format
}
}
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();
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.
/// <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).
Figure 19 displays debugging information after the client receives the status of a message.
Figure 19 Debug Information after Message Status
do
{
GetReturnMessagesResult result = SVC.GetReturnMessages(myAccessID, myPassword,
filter);
if (result != null && result.ErrorID == 0)
{
// 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());
}
}
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
do
{
GetReturnMessagesResult result = SVC.GetReturnMessages(myAccessID, myPassword,
filter);
if (result != null && result.ErrorID == 0)
{
// 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);
}
if (result.NextStartID > 0)
filter.StartMessageID = result.NextStartID;
}
}
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
Requires authentication: No
Response formats: json, xml
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
Requires authentication: No
Response formats: json, xml
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
Response formats: json, xml
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"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorID>0</ErrorID>
<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
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorID>0</ErrorID>
<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>
<LastRegistrationUTC>2012-09-13 20:55:35</LastRegistrationUTC>
<RegionName>AMERRB16</RegionName>
</MobileExInfo>
<MobileExInfo>
<ID>01000057SKY9E9A</ID>
<Description>Rev2</Description>
<LastRegistrationUTC>2011-11-17 14:56:05</LastRegistrationUTC>
<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
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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
<GetReturnMessagesResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorID>0</ErrorID>
<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
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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:
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
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,
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
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"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorID>0</ErrorID>
<More>true</More>
<NextStartUTC>2011-07-22 14:23:02</NextStartUTC>
<Statuses>
<ForwardStatus>
<ForwardMessageID>964363</ForwardMessageID>
<IsClosed>true</IsClosed>
<State>RECEIVED</State>
<ErrorID>0</ErrorID>
<StateUTC>2011-06-29 13:44:25</StateUTC>
<ReferenceNumber>1030</ReferenceNumber>
</ForwardStatus>
<ForwardStatus>
<ForwardMessageID>964960</ForwardMessageID>
<IsClosed>true</IsClosed>
<State>DELIVERY_FAILED</State>
<ErrorID>12309</ErrorID>
<StateUTC>2011-06-29 15:38:35</StateUTC>
<ReferenceNumber>135</ReferenceNumber>
</ForwardStatus>
…
8.9 get_forward_messages
Returns contents of forward messages. Equivalent to SOAP web service operation
GetForwardMessages().
Rate limited: Yes
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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"
},
"ReferenceNumber": 729
},
{
"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"
},
"ReferenceNumber": 67
}
]
}
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"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorID>0</ErrorID>
<Messages>
<ForwardMessageRecord>
<ID>1153034</ID>
<StatusUTC>2011-08-04 20:38:34</StatusUTC>
<CreateUTC>2011-08-04 20:38:26</CreateUTC>
<IsClosed>true</IsClosed>
<State>RECEIVED</State>
<DestinationID>01000056SKY1A95</DestinationID>
<ErrorID>0</ErrorID>
<RawPayload>FwUA</RawPayload>
<Payload Name="getDataLogEntries" SIN="23" MIN="5" IsForward="True"/>
<ReferenceNumber>729</ReferenceNumber>
</ForwardMessageRecord>
<ForwardMessageRecord>
<ID>1151791</ID>
<StatusUTC>2011-08-04 16:02:35</StatusUTC>
<CreateUTC>2011-08-04 15:47:55</CreateUTC>
<IsClosed>true</IsClosed>
<State>RECEIVED</State>
<DestinationID>16777178GRP557F</DestinationID>
<ErrorID>0</ErrorID>
<RawPayload>AGI=</RawPayload>
<Payload Name="RequestLastRxMetrics" SIN="0" MIN="98" IsForward="True"/>
<ReferenceNumber>67</ReferenceNumber>
</ForwardMessageRecord>
</Messages>
</GetForwardMessagesResult>
8.10 submit_messages
Submits multiple messages to their destinations. Equivalent to SOAP web service
operation SubmitForwardMessages().
Rate limited: Yes
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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": [
{
"DestinationID": "01000056SKY1A95",
"UserMessageID": 101,
"RawPayload": [16,1]
}
]
}
Response
{
"SubmitForwardMessages_JResult": {
"ErrorID": 0,
"Submissions": [
{
"ForwardMessageID": 1209801,
"DestinationID": "01000056SKY1A95",
"StateUTC": "2011-08-23 17:24:05",
"ErrorID": 0,
"UserMessageID": 101
}
]
}
}
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messa
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
Expect: 100-continue
Connection: Keep-Alive
Response
8.11 submit_messages_to_destinations
Submits a message to multiple destinations. Equivalent to SOAP web service operation
SubmitForwardMessageToMultipleDestinations().
Rate limited: Yes
Requires authentication: Yes
Response formats: json, xml
HTTP methods: POST
Resource URL
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages_to_dest
inations.json/
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages_to_dest
inations.xml/
Parameters
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
destinations (required) A list of coma separated destinations the message
needs to be sent to
message (required) A ForwardMessage object
Example Requests
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messa
ges_to_destinations.json/
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages_to_dest
inations.json/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: 172.20.101.174
Content-Length: 165
Expect: 100-continue
Connection: Keep-Alive
{
"accessID": "70000001",
"password": "password",
"destinations": "01000056SKY1A95,01000056SKY1A95",
"message": {
"DestinationID": "",
"UserMessageID": 0,
"RawPayload": [16,1]
}
}
Response
{
"ErrorID": 0,
"Submissions": [
{
"ForwardMessageID": 1209936,
"DestinationID": "01000056SKY1A95",
"StateUTC": "2011-08-23 18:12:21",
"ErrorID": 0,
"UserMessageID": 0
},
{
"ForwardMessageID": 1209937,
"DestinationID": "01000056SKY1A95",
"StateUTC": "2011-08-23 18:12:21",
"ErrorID": 0,
"UserMessageID": 0
}
]
}
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messa
ges_to_destinations.xml/
POST
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/submit_messages_to_dest
inations.xml/ HTTP/1.1
Content-Type: application/xml; charset=utf-8
Host: ott-svrbaskilap.skywavemobile.com
Content-Length: 410
Expect: 100-continue
Connection: Keep-Alive
<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
8.12 submit_cancelations
Submits cancellation request for specified messages. Equivalent to SOAP web service
operation SubmitMessageCancelations() (Section 4.3.3).
Rate limited: Yes
Requires authentication: Yes
Response formats: json, xml
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
access_id (required) Customers' IDP Gateway access ID
password (required) Customers' IDP Gateway password
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
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
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
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.
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).
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.
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.
REST:
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
tatuses.xml/?access_id=70000999&password=0X0X0GB6&fwIDs=338882,338884
OR,
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
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:
ForwardStatusFilter filter = new ForwardStatusFilter();
// 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
REST:
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
tatuses.xml/?access_id=70000999&password=0X0X0GB6&start_utc=2013-09-
25%2015:00:20
OR,
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_forward_s
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.
REST:
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_return_m
essages.xml/?access_id=70000111&password=K101H1B1&from_id=2987645
OR,
http://isatdatapro.skywave.com/GLGW/GWServices_v1/RestMessages.svc/get_return_m
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.
sleepInMilliseconds = 30 * 1000;
}
}
else if (result != null && result.ErrorID == ERR_CUSTOMER_DELAYED)
{
// Calling the web service too often - Extend the sleep time again.
sleepInMilliseconds = 30 * 1000;
}
if(sleepInMilliseconds > 0)
Sleep(sleepInMilliseconds);
} while (!done);
// Calling the web service too often - Extend the sleep time again.
sleepInMilliseconds = 30 * 1000;
}
if(sleepInMilliseconds > 0)
Sleep(sleepInMilliseconds);
} while (!done);
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:
Enter a valid mobile ID from your IGWS account.
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:
Enter a valid mobile ID from your IGWS account.
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