Btraced Webservice and Messages

Forum / topics about Btraced protocol and webservice (uploading gps data) Also Btraced sample code.

Btraced Webservice and Messages

Postby Btraced » Sat Mar 24, 2012 10:35 pm

From your own server its possible to send messages to the App on the iPhone
In some situation its also needed to do this, otherwise the Btraced app does not know the points are uploaded.
Uploaded points are store in the app on the phone. so if you miss some uploads you can always sent only those later.
its also possible to reset all upload points for a trip in the app, after this is done all points can be uploaded again to any server of choice!

Every time the webservice receives a post message from the Btraced app, it should answer with a response in JSON format.
There are multiple type of answers that can be used. They are described here.

In general lines, here are all the possible fields:

ID:
Answer type (a value to identify the type of answer)

TripID:
The internal btraced trip number which the server answer is related to

Points:
An array with the internal brtaced points ID which were successfully saved into the server

Valid:
Should be always set “true” so Btraced can idenfity a valid JSON message

Error:
set to true if there was an error. Ignore this field or set to no if there wasn’t any error

Message:
Here there can be any custom message string for an error

ExtraData:
An array of extra data needed for special types of messages

Message Type 0: Success
Example:
{
"id":0,
"tripid":3,
"points":[301, 302, 303, 304, 305, 306, 307, 308],
"valid":true
}

The message type for this message is 0. It’s used to send an acknoledge signal of the saved points in the server.
In this example, the webservice is confirming that the points 301 to 308 for trip ID 3 were successfully stored in the server database.
This message will make Btraced app to update the trip status and flag those points as “Uploaded” state. It should be an array of integer values, even if it’s just one point.

Message Type 1: Empty username or password
Example:
{
"id":1,
"error":true,
"valid":true
}

This message is used to notify an invalid username or password in case the webservice requires an user validation. If message field is set, it will be ignored as it’s a known message type. For custom messages see next messages.

Message Type 3: Upload limit reached
Example:
{
"id":3,
"extradata":[300],
"tripid":3,
"points":[301, 302, 303, 304, 305, 306, 307, 308],
"error":true,
"valid":true
}

In this case, it will notify Btraced that the server has an upload limit on points for each trip.
In extradata array, the first value is the amount of points permitted by trip in the server.
This will show the limitation message with the limit value sent in the message.
As the limit can occur with a set of points of the upload, the trip id and points should be set to identify those points that were successfully added to the server datase. For example if the limit of points are 300, we already upload 290 points, and the XML sent by Btraced are for 30 points, then the first 10 points should be stored and reported as “Uploaded”, while the remaining 20 will be not saved in the server and neither should be in the “points” array.

Message Type >900: Custom messages
All the messages with ID number over 900, are used for custom messages not included in Btraced and that the server need to report. These messages can include any combination of the above fields. If the tripid and points field are shown, then those points will be updated to “uploaded” state in Btraced.
If the message and error fields are set to a string and true value, then the custom message will be shown in the Btraced application.
Example:
{
"id":905,
"tripid":3,
"points":[301, 302, 303, 304, 305, 306, 307, 308],
"error":true,
"message":”This is a custom server message”,
"valid":true
}

With this message, Btraced will set points 301 to 308 of trip ID 3 to “uploaded” state. Also it will popup a message with the string in the JSON answer (or show the warning sign).
All the custom messages must have the same ID for the same message. Different messages should have a different ID.

Here is a the complete webservice protocol document
Btraced Protocol v1.0.zip
User avatar
Btraced
Site Admin
 
Posts: 60
Joined: Sat Dec 10, 2011 3:03 pm

Return to Btraced Webservice Protocol And Sample code etc.

Who is online

Users browsing this forum: No registered users and 1 guest

cron