Send Binary Message
sendBinaryMessage
This web service is used to create a forward binary message and queue it for transmission to a list of destinations (addressees). A global message handle is returned. Transactions indicating the disposition of transmitted messages will be available through ESS.
int sendBinaryMessage(String addressees, boolean returnReceipt, int priority, int virtualChannel, byte[] body) throws WSException
-
addressees: is a comma delimited string containing the addressees (destinations) of the message. The addressees may be vehicles, groups of vehicles, indirect users, indirect groups of users or any combination thereof. A single message may be addressed to up to 20 addressees. If the addressee is indirect, attach the '@" symbol in front of the addressee.
SCAC/Vehicle ID's are supported. Valid SCAC/Vehicle ID format is:SCAC|Vehicle ID
Send the message to the specified vehicle
In both cases, the if the vehicle ID has leading zeros, they are required. Leading or trailing blanks for the SCAC or the Vehicle ID may be omitted.
Fleetwide addressing is supported. Possible values are:*ALLVEH
send message to all vehicles
- returnReceipt a boolean that when set to true indicates that a notification indicating that the message has been read should be returned through ESS.
- priority an integer indicating the Message Priority of the forward message. See the panel below for a detailed description.
- virtualChannel an integer indicating the virtual channel over which the message body will be sent. The valid range is 3, and 322 - 999.
- body The body of the binary message is a byte array that may contain up to 4,000 elements.
Message Priorities
The priority controls how the NOC delivers a forward message to the vehicle as described below.
Group messages are transmitted 12 times over 85 minutes, regardless of priority except for Extended Sleepy. Extended Sleepy group messages are transmitted 20 times over 72 hours.
|
Priority |
Transmission Attempts |
|
0 - Normal |
9 times over 35 minutes |
|
1 - Important |
9 times over 35 minutes |
|
2 - Sleepy |
7 times over 18.25 hours |
|
3 - Sleepy-Important |
7 times over 18.25 hours |
|
5 - Attention |
9 times over 35 minutes |
|
6 - Extended Sleepy |
10 times over 72 hours |
|
9 - Emergency |
10 times over 35 minutes |
Unlike other types of mobile units, MCP50 and IVG units do not have a wakeup timer to scan for messages over long periods when the unit is off or out of coverage. If you send messages to MCP50 or IVG-equipped vehicles select the Sleepy, Sleepy Important (Sleepy+), or Extended Sleepy message priority, because it attempts transmission over a longer period of time. For example, the Extended Sleepy message priority allows a message to be sent on a Friday and received on a Monday when the truck ignition is turned on after being powered off for the weekend.
Authorization Requirements
The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.
Required Application Licenses
- Remote Integration
Required User Permissions
- Can use QTRACS
- Can send OTA binary messages
- Can send message to fleet, in order to send a message to all vehicles
- Can send emergency priority messages, if the priority parameter is set to emergency
- Can send attention messages, if the priority is 5
- Can see data for all assets OR the vehicle must be in the user's coverage or global group
Customer integrators are authorized to their own company's data only.
Message Body Form
The body of the binary message is a byte array. The body may consist of XML, text, a comma delimited string or an array of bytes with the underlying meaning of the data at the bit level where each byte does not have to represent a specific character. The sender has the ultimate in flexibility when it comes to what can be sent via the body of the binary message. This message will not be modified in any way by the host and will just be passed along to the mobile.
Please note that the binary message data is defined in the WSDL as XML data type xsd:base64Binary. You will need to employ a base64Binary encoder to translate the ASCII or Unicode binary message being sent. Some platforms have built-in functions to do this. .NET and Java are such examples. Other platforms will require you download and use a library containing the base64Binary encoder. A Google search for your platform with the term "base64 encoder" will likely show several freely available algorithms for encoding base64Binary data. The algorithm is well defined and rather simple to replicate.
Exceptions
002 Required field not specified.
003 Company not authorized for access through integration.
004 User is not authorized.
005 Destination must be specified.
006 Message body cannot be empty.
007 Invalid Return receipt.
008 Invalid priority specified.
009 User is not authorized to send attention messages.
010 User is not authorized to send emergency messages.
011 Invalid virtual channel specified.
012 User is not authorized to send messages to all vehicles.
013 Invalid destination.
014 Destination not found.
015 Wildcard destination cannot be indirect.
016 Only one destination allowed when there is a wildcard destination.
017 Destination is an auxiliary vehicle but QMASS is not turned on.
018 Destination must be a vehicle or indirect to a vehicle.
019 Maximum of 20 destinations may be specified.
020 User is not authorized to send OTA binary messages.
021 Message body exceeds allowable line limit.
022 Failure sending message. A specific reason will be returned to the client for message failure.
023 Cannot send a message to a vehicle without a device.
Sample sendBinaryMessage Request
|
|
Sample sendBinaryMessage Response
|
|