Client (HHP) to TV Application Communication
REST Interface
The communication path from the client device (HHP) to the TV application is provided via the REST interface. The following calls are designed to be a generic set of communication APIs that allow developers to define the content of the messages, while providing a structured protocol easily understood by the server (TV).
Each of the following requests includes a URI that contains an {appID}, which is required to communicate with the corresponding TV application.
Request Headers
Header | Description | Required |
---|---|---|
SLDeviceID | This header contains the DeviceID used to identify the client device and the corresponding TV application. | YES (for ALL requests except Get Application Info request) |
Content-Type | This header refers to the content type of the request. The value for this header can be either application/json or text/xml. | YES (for POST requests only) |
ProductID |
This header is only required for Device Connect requests. The value MUST begin with “SMART” and be exactly 8 characters long. Example: SMARTTVI |
YES (for Connect requests only) |
VendorID | This header is only required for Device Connect requests. The value must be exactly 8 characters long. | YES (for Connect requests only) |
DeviceName | This header is only required for Device Connect requests. This header contains the name of the client device. The value MUST be less than 64 characters long. | YES (for Connect requests only) |
User-Agent | This header is used by the TV to identify the type of the client device and its capabilities. | YES (for ALL requests) |
Custom (User-Defined) | The developer can add any other headers needed for proper performance of their application. Any custom headers added to a request are included as the second parameter in the message context (JSON object). | NO |
Application Methods
Get Application Info
This request retrieves the following information related to the application ID included in the request. This is a system message and the message format is predefined in JSON format.
HTTP method and URI GET /ws/app/{appID}/info |
||
---|---|---|
Syntax | Request type: GET URI: /ws/app/{appID}/info | |
Return value |
For example: {"widgetInfo": {"ID": "Canvas_NewOCI", "Version": "0.930", "Status": "RUNNING", "widgetname": "sampleWidget"}} |
|
Parameter |
|
|
Example |
Sample request: GET /ws/app/sampleWidget/info HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 192.168.1.108
Accept: */*
Sample response: HTTP/1.1 200 OK
Content-Type: text/html
Transfer-Encoding: chunked
Date: Thu, 14 Jul 2011 22:16:25 GMT
Server: lighttpd/1.4.28
{"widgetInfo": {"ID": "Canvas_NewOCI", "Version": "0.930", "Status": "RUNNING", "widgetname": "sampleWidget"}} |
Connect to Application
This request initiates the connection between the client application and the TV application. Client must provide the following headers with the request:
- SLDeviceID: Client’s Device ID. The ID is translated by TV M/W and there will be 1-to-1 mapping to device ID passed to TV application.
- VenderID: Vendor ID. It should be provided by Samsung and should be 8 characters exactly.
- ProductID: Product ID. It should be provided by Samsung and should be 8 characters exactly.
HTTP method and URI POST /ws/app/{appID}/connect |
|
---|---|
Syntax | Request Type: POST URI: /ws/app/{appID}/connect |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/connect HTTP/1.1
Accept: */*
Accept-Language: en-us
SLDeviceID: 12345
VendorID: VenderMe
DeviceName: IE-Client
ProductID: SMARTDev
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 127.0.0.1:8080 Content-Length: 0
Connection: Keep-Alive
Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|
Disconnect from Application
This request disconnects the mobile application from the TV application.
HTTP method and URI POST /ws/app/{appID}/disconnect |
|
---|---|
Syntax | Request type: POST URI: /ws/app/{appID}/disconnect |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/disconnect
HTTP/1.1 Accept-Encoding: gzip, deflate
Accept-Language: en-us
SLDeviceID: 12345
Accept: */*
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 192.168.1.108
Content-Length: 0
Connection: Keep-Alive
Pragma: no-cache
Sample response: HTTP/1.1
200 OK
Content-Length: 0
Date: Thu, 01 Jan 1970 01:32:23 GMT
Server: lighttpd/1.4.28
|
Message Queue Methods
Each of the following requests is designed to communicate directly with the message queueing system on the TV. These REST APIs are limited to either pushing a message onto the queue or popping (removing) a message from the queue.
Message from Mobile App to TV App
This request pushes a TV application message onto the message queue in the TV. Any message sent to the following URI only goes to the TV application.
Note
The message body included in this request is determined by the developer of the application.
HTTP method and URI POST /ws/app/{appID}/queue Push message (to TV App): To send application data to TV App |
|
---|---|
Syntax | Request type: POST URI: /ws/app/{appID}/queue |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/queue HTTP/1.1
Accept: application/json
Accept-Language: en-us
SLDeviceID: 12345
Content-Type: application/json
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 192.168.1.108
Content-Length: 56
{"type":"touchMove","coordinates":{"x":"343","y":"252"}} Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|
Pop Message
If the message queue is not empty, this request retrieves a message from the device’s message queue on the TV. If the message queue is empty, this request is be held until the message arrives or the request times out (long polling). Status code 408 is returned upon long polling time out. The client must initiate another pop message request immediately when it receives 408.
HTTP method and URI GET /ws/app/{appID}/queue/devices/{deviceID} Push message (from TV App): To get application data from TV App |
|
---|---|
Syntax | Request type: GET URI: /ws/app/{appID}/queue/devices/{deviceID} |
Return value |
|
Parameter |
|
Example |
Sample request: GET /ws/app/Canvas_NewOCI/queue/devices/12345 HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 127.0.0.1:8080
Accept: application/json
SLDeviceID:12345
Sample response: HTTP/1.1 200 OK
Content-Type: application/json
sender: TV
Transfer-Encoding: chunked
Date: Fri, 15 Jul 2011 21:01:59 GMT
Server: lighttpd/1.4.28
{"type":"echo","coordinates":{"x":"343","y":"252"}} |
Device Group Methods
Join Group
This request is sent to inform the TV that the device wants to join a particular group.
HTTP method and URI POST /ws/app/{appID}/queue/groups/{groupID}/join |
|
---|---|
Syntax | Request type: POST URI: /ws/app/{appID}/queue/groups/{groupID}/join |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/queue/groups/feigroup/join HTTP/1.1
SLDeviceID:12345
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Content-Length: 0
Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|
Leave Group
This request is sent to inform the TV that the device wants to leave a particular group.
HTTP method and URI POST /ws/app/{appID}/queue/groups/{groupID}/leave |
|
---|---|
Syntax | Request type: POST URI: /ws/app/{appID}/queue/group/{groupID}/leave |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/queue/groups/feigroup/leave HTTP/1.1
SLDeviceID:12345
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Content-Length: 0
Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|
List Group Members
This request retrieves a list of all devices currently joined to a particular group.
HTTP method and URI GET /ws/app/{appID}/queue/groups/{groupID} |
|
---|---|
Syntax | Request type: GET URI: /ws/app/{appID}/queue/group/{groupID} |
Return value |
|
Parameter |
|
Example |
Sample request: GET /ws/app/sampleWidget/queue/groups/Canvas_NewOCI
HTTP/1.1 User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1
OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 127.0.0.1:8080
Accept: application/json
SLDeviceID:12345
Sample response: HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 15 Jul 2011 21:10:10 GMT
Server: lighttpd/1.4.28
{"group":{"Devices":[{"SLDeviceID":"12345"},]}} |
File Upload Methods
It is also possible to send files to the corresponding TV application. In these requests, the content type must be multipart form data. Multiple messages and files may be sent together. Each message has a separate callback on the TV application. Client devices can then access the uploaded files through the following URI: /ws/app/{appID}/file/{filename} .
The size limit for single uploaded file and total uploaded files is 3MB. All the uploaded files will be cleaned up when the TV application quits execution.
Upload File
This request sends a message containing the file data to the message queue on the TV.
Content type must be Multipart form data. Multiple messages and files can be sent together. Each message will be a separate callback on application. Files are saved and served through URI: /ws/app/{appID}/file/{filename} .
HTTP method and URI POST /ws/app/{appID}/queue |
|
---|---|
Syntax | Request type: POST URI: /ws/app/{appID}/queue |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/queue HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 192.168.1.108
Accept: */*
SLDeviceID: 12345
Content-Length: 13774
Expect: 100-continue
Content-Type: multipart/form-data;
Content-Disposition: form-data; name="message"
{"type": "ShowPic", "filename": "UE-1.jpg"} Content-Disposition: form-data; name="upload";
filename="UE-1.jpg"
Content-Type: image/jpeg
...
Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|
Delete File
This request will delete a file on the TV.
HTTP method and URI DELETE /ws/app/{appID}/file/{filename} |
|
---|---|
Syntax | Request type: DELETE URI: /ws/app/{appID}/file/{filename} |
Return value |
|
Parameter |
|
Example |
Sample request: POST /ws/app/sampleWidget/file/test1.jpg HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 192.168.1.108
Accept: */*
SLDeviceID: 12345
...
...
Sample response: HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28
|