Cisco TV CDS 2.0 API Guide

Transcription

1 March 2009 Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax: Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. CCDE, CCENT, Cisco Eos, Cisco HealthPresence, the Cisco logo, Cisco Lumin, Cisco Nexus, Cisco StadiumVision, Cisco TelePresence, Cisco WebEx, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn and Cisco Store are service marks; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iphone, iquick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0812R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface v Document Revision History v Audience v Document Organization vi Document Conventions vi Related Documentation vii Obtaining Documentation and Submitting a Service Request vii CHAPTER 1 Introduction to Cisco TV CDS Software APIs 1-1 Connection 1-1 HTTP Headers 1-2 Request Messages 1-2 Monitoring Requests 1-2 RTSP Stream Diagnostics Requests 1-2 Response Messages 1-4 Monitoring Response 1-4 RTSP Stream Diagnostics Response 1-4 Message Flow for RTSP Stream Diagnostics APIs 1-5 Request and Response 1-5 Request Timeout 1-5 Invalid Sequence Number 1-5 Connection Lost 1-5 CHAPTER 2 Monitoring APIs 2-1 MaxErrorModifiedTime 2-1 MaxStreamModifiedTime 2-2 StreamHistory 2-3 TrickModeHistory 2-5 Errors 2-6 Devices 2-7 ServiceGroups 2-8 ContentState 2-9 Version 2-11 iii

4 Contents CHAPTER 3 RTSP Stream Diagnostics APIs 3-1 StreamsBySmartcard 3-1 GetStreamDetailsBySessionId 3-3 GetStreamTrickmodesBySessionId 3-4 iv

5 Preface This preface describes the audience, use, and organization of the. The preface also outlines the document conventions and support information. It contains the following sections: Document Revision History, page v Audience, page v Document Organization, page vi Document Conventions, page vi Related Documentation, page vii Obtaining Documentation and Submitting a Service Request, page vii Document Revision History The Document Revision History table records technical changes to this document. Document Revision Date Change Summary March 4, 2009 Initial release Audience This application program interface (API) guide is written for the knowledgeable application programmer who understands the basic architecture of the Cisco TV Content Delivery System (CDS) software product, extensible Markup Language (XML), and HTTP POST calls. This guide is not intended to direct the user in how to program in XML and limits itself to describing how related CDS APIs are used. v

6 Preface Document Organization This document contains the following chapters: Chapter or Appendix Chapter 1, Introduction to Cisco TV CDS Software APIs Chapter 2, Monitoring APIs Chapter 3, RTSP Stream Diagnostics APIs Descriptions Provides an overview of the Cisco TV CDS APIs. Describes the monitoring APIs, including streams, content, and devices. Describes APIs for the RTSP environment. Document Conventions This guide uses the following conventions for command syntax descriptions and textual emphasis: Conventions boldface font italic font Descriptions Commands and keywords are in boldface. Arguments for which you supply values are in italics. [ ] Elements in square brackets are optional. {x y z} Alternative, mutually exclusive, keywords are grouped in braces and separated by vertical bars. [x y z] Optional alternative keywords are grouped in brackets and separated by vertical bars. string A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks. screen font Terminal sessions and information the system displays are in screen font. boldface screen font italic screen font Information you must enter is in boldface screen font. Arguments for which you supply values are in italic screen font. ^ The symbol ^ represents the key labeled Control for example, the key combination ^D in a screen display means hold down the Control key while you press the D key. < > Nonprinting characters, such as passwords, are in angle brackets in contexts where italics are not available.!, # An exclamation point (! ) or a pound sign ( # ) at the beginning of a line of code indicates a comment line. Caution Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data. vi

7 Preface Note Means reader take note. Notes contain helpful suggestions or references to materials not contained in this publication. Tip Means the following information might help you solve a problem. Related Documentation These documents provide complete information about the CDS and are available from Cisco.com: Release Notes for the Cisco TV CDS 2.0 Cisco TV CDS 2.0 ISA Software Configuration Guide Cisco TV CDS 2.0 RTSP Software Configuration Guide Cisco Content Delivery Engine 100/200/300/400 Hardware Installation Guide Cisco Content Delivery Engine 110 Hardware Installation Guide Cisco Content Delivery Engine 205/220/420 Hardware Installation Guide Cisco Content Delivery System 2.x Documentation Roadmap Regulatory Compliance and Safety Information for Cisco Content Delivery Engines You can access the software documents at the following URL: You can access the hardware documents at the following URL: Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: Subscribe to the What s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0. vii

8 Preface viii

9 CHAPTER 1 Introduction to Cisco TV CDS Software APIs Cisco TV Content Delivery System (CDS) software provides two sets of application program interfaces (APIs): Monitoring Real Time Streaming Protocol (RTSP) Stream Diagnostics The Monitoring APIs use an HTTP GET message format for sending control messages between any HTTP client and the Cisco CDS. The RTSP Stream Diagnostics APIs use extensible Markup Language (XML) over Hypertext Transfer Protocol (HTTP) for sending control messages between any HTTP client and the Cisco CDS. The APIs can be used to monitor the states of specified CDS functions. Table 1-1 describes these APIs. Table 1-1 API Monitoring RTSP stream diagnostics Cisco TV CDS APIs Description Returns information on content states, stream history, trick-mode history, as well as other information about the devices. Returns information about streams and trick modes for a specified session ID in an RTSP environment, as well as stream information about a specified smart card. A smart card is a unique ID that represents a set-top box (STB). This chapter contains the following sections: Connection, page 1-1 HTTP Headers, page 1-2 Message Flow for RTSP Stream Diagnostics APIs, page 1-5 Connection Any HTTP client that can send a request to the Content Delivery System Manager (CDSM) in the proper format can be used to send the API messages. Connections can be semi-persistent or persistent; that is, the connection can be used for a single request-response pair or multiple request-response pairs. A standard set of HTTP headers is used for all HTTP requests and responses. These headers include the content type, the content length, and a sequence number. 1-1

10 HTTP Headers Chapter 1 Introduction to Cisco TV CDS Software APIs The HTTP request transmitter is considered the client and the HTTP request receiver is considered the server. The client always initiates the connection. The client must either receive a response or time out a request before sending another request on the same connection. The same connection can be used for multiple requests. However, when the client sends a new request, if there is already a connection established for a previous request for which the client is expecting a response from the server, then the client must open a new connection for the new request. The API messages require a bidirectional socket connection for sending an HTTP request and receiving an HTTP response. The persistent protocol maintains a connection between requests until either the client or server indicates that the socket should close. This is typical of HTTP/1.0. Persistent connections are handled using the traditional mechanisms specified in HTTP. In HTTP/1.0, connections are persistent by default. The HTTP response must include the header Connection: close in order to indicate that the connection will be closed at the end of transmission. During periods when no messages are being exchanged, the client or server may close the connection to conserve resources. The recommended connection approach is to use the default HTTP/1.0 behavior and to use the same connection for all requests. HTTP Headers This section covers the HTTP header formats for the request messages and the response messages. Request Messages Monitoring Requests There are two different request message formats: Monitoring requests HTTP GET RTSP Stream Diagnostics request HTTP POST The Monitoring APIs use an HTTP GET message format. All parameters are included in the HTTP GET message. Table 1-2 provides an overview of the expected input parameters for each request message. Table 1-2 Request Parameters Parameter Required or Optional Description messagetype Required Always required. fromdate Required for Required for StreamHistory, TrickModeHistory, and Errors. time-based messages todate Required for Required for StreamHistory, TrickModeHistory, and Errors. time-based messages maxrows Optional Specifies the maximum number of rows to return for this result set. Available for all messages. 1-2

11 Chapter 1 Introduction to Cisco TV CDS Software APIs HTTP Headers Table 1-2 Request Parameters (continued) fromoffset Optional Specifies the row offset to start returning for this result set. A zero-based offset. Available for all messages. dateformat Optional Specifies the formatting of the fromdate and todate parameters to be seconds or milliseconds since epoch. The default is seconds. This parameter does not affect the output formatting of dates in the return message. The options are sec or ms. RTSP Stream Diagnostics Requests Session Optional Specifies what type of error messages to retrieve from the CDS. The options are: For RTSP Stream Diagnostic requests, regardless of the request type, the same HTTP request header format is used. Basic request requirements include the following: All requests are sent by means of POST. The Uniform Resource Identifier (URI) specifies the root XML tag. The HTTP version is 1.0. Entity-bodies are used to convey XML data. Required entity headers are the following: content-length: Bytes (length of XML data) content-type: text/xml cseq: Unique numeric ID 1 Retrieve only session-related error messages. Other entity headers are optional. For example, the HTTP header may include a date header. However, non-required entity headers may be ignored by the server. The URI specifies the root service for the message followed by the query string. The query string has the syntax of action=<xml root tag>. The URI always begins with the service name. For example, if the service name is PlayoutDetails and the XML root tag is <GetCurrentlyPlayingDetails>, the URI is /apis/playoutdetails?action=getcurrentlyplayingdetails. The following example is the complete HTTP POST message: 2 Retrieve only error messages not session-related (no session ID). 3 Retrieve all error messages. The default is 3. POST /apis/playoutdetails?action=getcurrentlyplayingdetails HTTP/1.0 User-Agent: HTTPTool/1.0 Content-Type: text/xml Content-Length: 60 CSeq: 123 <?xml version="1.0" encoding="utf-8"?> <GetCurrentlyPlayingDetails /> 1-3

12 HTTP Headers Chapter 1 Introduction to Cisco TV CDS Software APIs Response Messages There are two different response message formats: Monitoring response RTSP Stream Diagnostics response Monitoring Response All response messages for the Monitoring APIs return an XML document. RTSP Stream Diagnostics Response The same HTTP response header is used regardless of the response type. The status code and status text in the response indicate whether the server received and processed the request. Some HTTP response messages consist of only the HTTP header, while others consist of both the HTTP header and XML message body. The only required entity header is cseq, which is a unique numeric identifier. The only required entity header for the XML message body is the content-type, text/xml. Other entity headers are optional. For example, the HTTP header may include a date header. However, non-required entity headers may be ignored by the client when processing the response. The sequence number specified in the HTTP response must match the sequence number in the HTTP request. The status codes and status text are specific to the HTTP-response. Chapter 2, Monitoring APIs and Chapter 3, RTSP Stream Diagnostics APIs provide a list of appropriate status codes for each message. The following example is an HTTP response with no XML body: HTTP/ OK Date: Mon, 02 Jun :50:45 GMT CSeq: 123 The following example is an HTTP response with the XML body (body not shown): HTTP/ OK Date: Mon, 02 Jun :50:45 GMT Server: Apache/ (UNIX) PHP/4.4.8 X-Powered-By: PHP/4.4.8 Connection: close Content-Type: text/xml CSeq:

13 Chapter 1 Introduction to Cisco TV CDS Software APIs Message Flow for RTSP Stream Diagnostics APIs Message Flow for RTSP Stream Diagnostics APIs This section covers the HTTP message flow and possible causes for incomplete message transactions. Request and Response The client connects to the server, sends an HTTP request, and waits for an HTTP response. During this time, the client must not send any other requests using this connection. The client can establish a separate connection to send another request in parallel. The server processes the request and sends an HTTP response to the client on the same connection on which it received the request. The response must use the same sequence number that was specified in the request. When the client receives the response, it validates the sequence number before processing the response. Based on the HTTP headers, the client or server may close the connection or the connection may be left open for subsequent requests from the client. The client can have several open connections to the server at any given time. Request Timeout The client sets a timer when it sends an HTTP request. This timer represents the maximum amount of time the client waits for a response from the server. A typical timeout period is five seconds. If the client fails to receive an HTTP response before the timer expires, the client must consider the request as failed. The client can discard the request, immediately retry the request, or retry the request at a later time. The method of handling the failure is implementation-specific, and may vary by importance of the request type. Invalid Sequence Number When the client receives an HTTP response with a sequence number that differs from the request sequence number, the client discards the message and continues to wait for a valid response until the timeout threshold has been reached. Connection Lost During the HTTP transaction, if the connection to the server is lost at any time prior to receiving a valid HTTP response message, the client must consider the request has failed. The client should immediately retry the request. If the retry fails, the client can discard the request or retry the request at a later time. The method of handling the failure is implementation-specific, and may vary by the importance of the request type. In most cases, the server has started processing the request prior to the connection loss. The server should finish processing the request. The server must not establish a connection with the client in order to return the response. It is up to the client to reconnect and retransmit the request. 1-5

14 Message Flow for RTSP Stream Diagnostics APIs Chapter 1 Introduction to Cisco TV CDS Software APIs 1-6

15 CHAPTER 2 Monitoring APIs This chapter describes the format and content of the Monitoring API messages. The Monitoring API messages consist of the following: MaxErrorModifiedTime, page 2-1 MaxStreamModifiedTime, page 2-2 StreamHistory, page 2-3 TrickModeHistory, page 2-5 Errors, page 2-6 Devices, page 2-7 ServiceGroups, page 2-8 ContentState, page 2-9 Version, page 2-11 Note Devices, Applications, ServiceGroups, ContentState, and Version response messages are not time-sensitive and always return the current state of the requested information. All HTTP request messages for the Monitoring APIs follow the HTTP GET format. All response messages for the Monitoring APIs return an XML document. MaxErrorModifiedTime The MaxErrorModifiedTime request-response message returns the timestamp of the latest error in the database. Request Required: MaxErrorModifiedTime Request Example 2-1

16 MaxStreamModifiedTime Chapter 2 Monitoring APIs Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The MaxErrorModifiedTimeResponse element is returned in the XML body response. Table 2-1 describes the XML body elements and attributes returned in the MaxErrorModifiedTimeResponse element. Table 2-1 MaxErrorModifiedTimeResponse Element Attributes Data Types Descriptions MaxErrorModifiedTime list element Element that contains the information. 1. UNIX epoch time is T00:00:00Z maxtime xs:integer The latest time (since start of UNIX epoch time) that an error occurred in the database. 1 curtime xs:integer The current time on the CDSM (since the start of UNIX epoch time). 1 Response Example <?xml version="1.0" encoding="utf-8"?> <MaxErrorModifiedTimeResponse xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/maxerrormodifiedtime.xsd"> <MaxErrorModifiedTime maxtime=" " curtime=" " /> </MaxErrorModifiedTimeResponse> MaxStreamModifiedTime The MaxStreamModifiedTime request-response message returns the timestamp of the latest stream that was modified in the database. Request Required: MaxStreamModifiedTime Request Example Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The MaxStreamModifiedTimeResponse element is returned in the XML body response. Table 2-2 describes the XML body elements and attributes returned in the MaxStreamModifiedTimeResponse element. 2-2

17 Chapter 2 Monitoring APIs StreamHistory Table 2-2 MaxStreamModifiedTimeResponse Element Attributes Data Types Descriptions MaxStreamModifiedTime list element Element that contains the information. 1. UNIX epoch time is T00:00:00Z maxtime xs:integer The latest time (since start of UNIX epoch time) that a stream was modified in the database. 1 curtime xs:integer The current time on the CDSM (since the start of UNIX epoch time). 1 Response Example <?xml version="1.0" encoding="utf-8"?> <MaxStreamModifiedTimeResponse xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/maxstreammodifiedtime.xsd"> <MaxStreamModifiedTime maxtime=" " curtime=" " /> </MaxStreamModifiedTimeResponse> StreamHistory The StreamHistory request-response message returns a list of streams that were served during the specified period of time. Note We recommend using the Errors API call in association with the StreamHistory API call in order to view any error records pertaining to the session ID. Request Required: StreamHistory Required: fromdate Required: todate The request example uses the maxrows, fromoffset, and dateformat optional parameters. Request Example e= &maxrows= &fromoffset=0&dateformat=sec Response One of the following HTTP status codes are returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The StreamsResponse element is returned in the XML body response. Table 2-3 describes the XML body elements and attributes returned in the StreamsResponse element. 2-3

18 StreamHistory Chapter 2 Monitoring APIs Table 2-3 StreamsResponse Element Attributes Data Types Descriptions Stream list element Element that contains the stream information. starttime xs:integer Stream start time (since start of UNIX epoch time). 1 endtime xs:integer Stream end time (since start of UNIX epoch time). 1 dbtime xs:integer Time (since start of UNIX epoch time) this stream was recorded in the database. tsidoutputs xs:string Transport stream ID (TSID) output. macaddress xs:string MAC address of the set-top box (STB). serveripaddress xs:string IP address of the Streamer. servicegroup xs:integer Service Group used to send the stream. sessionid xs:string Session ID associated with this stream. streamtype xs:string Stream type (either user or sys) is used to differentiate between user-requested streams and system streams. contentname xs:string Name of the content. assetior xs:string Interoperable Object Reference (IOR) for the content. bitrate xs:integer Rate the content is being streamed, in bits per second. assetname xs:string Name used in the ADI metadata for a group of content objects that make up one asset. 1. UNIX epoch time is T00:00:00Z Response Example <?xml version="1.0" encoding="utf-8"?> <StreamsResponse dateformat="sec" xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/streams.xsd"> <Stream starttime=" " endtime=" " dbtime=" " tsidoutput="0" macaddress="emulatedsess" serveripaddress="" servicegroup="22" sessionid="emulatedsession: :14996: " streamtype="user" contentname="content info unknown: " assetior="" bitrate="" assetname=""/> <Stream starttime=" " endtime=" " dbtime=" " tsidoutput="0" macaddress="emulatedsess" serveripaddress="" servicegroup="22" sessionid="emulatedsession: :14997: " streamtype="user" contentname="content info unknown: " assetior="" bitrate="" assetname=""/> <Stream starttime=" " endtime=" " dbtime=" " tsidoutput="0" macaddress="emulatedsess" serveripaddress="" servicegroup="22" sessionid="emulatedsession: :15000: " streamtype="user" contentname="cclonghd_11.mpg" assetior="ior: c3a e e636f6d2f d6f64756c652f a312e c e e32322e39392e a f004e f f796f f d " bitrate=" " assetname="arroyoasset" /> </StreamsResponse> 2-4

19 Chapter 2 Monitoring APIs TrickModeHistory TrickModeHistory The TrickModeHistory request-response message returns a list of trick-mode actions for all sessions during the specified period of time. Request Required: TrickModeHistory Required: fromdate Required: todate The request example uses the maxrows, fromoffset, and dateformat optional parameters. Request Example Date= &maxRows=100000&fromOffset=0&dateFormat=sec Response One of the following HTTP status codes are returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The TrickModesResponse element is returned in the XML body response. Table 2-4 describes the XML body elements and attributes returned in the TrickModesResponse. Table 2-4 TrickModesResponse Element Attributes Data Types Descriptions TrickMode list element Element that contains the trick-mode information. NPT xs:integer The current normal play time (NPT). NPT starts at 0 at the start of the video, advances in real time in normal play mode, decrements in reverse mode, and is fixed when the video is paused. errortext xs:string Information on any errors that occurred during trick play. eventtime xs:integer Time (since start of UNIX epoch time) this trick mode was recorded in the database. 1 scale xs:string The direction and speed of play. sessionid xs:string Session ID associated with this stream. 1. UNIX epoch time is T00:00:00Z Response Example <?xml version="1.0" encoding="utf-8"?> <TrickModesResponse dateformat="sec" xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/trickmodes.xsd"> <TrickMode NPT="0" errortext="" 2-5

20 Errors Chapter 2 Monitoring APIs eventtime=" " scale="0" sessionid="c0a800f0db2a:: :664506::13" /> <TrickMode NPT="0" errortext="" eventtime=" " scale="1" sessionid="c0a800f0db2a:: :664506::13" /> <TrickMode NPT="0" errortext="" eventtime=" " scale="0" sessionid="c0a800f0db2a:: :664506::13" /> </TrickModesResponse> Errors The Errors request-response message returns a list of stream errors that occurred during the specified period of time. Request Required: Errors Required: fromdate Required: todate The request example uses the maxrows, fromoffset, and dateformat optional parameters. Request Example &maxRows= &fromOffset=0&dateFormat=sec Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The ErrorsResponse element is returned in the XML body response. Table 2-5 describes the XML body elements and attributes returned in the ErrorsResponse element. 2-6

21 Chapter 2 Monitoring APIs Devices Table 2-5 ErrorsResponse Element Attributes Data Types Descriptions Error list element Element that contains the error information. errorcode xs:integer Stream error code. errortext xs:string Stream error description. errortime xs:integer Time (since start of UNIX epoch time 1 ) this error was recorded in the database. 1 macaddress xs:string MAC address of the STB. serveripaddress xs:string IP address of the Streamer. 1. UNIX epoch time is T00:00:00Z Response Example <?xml version="1.0" encoding="utf-8"?> <ErrorsResponse dateformat="sec" xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/errors.xsd"> <Error errorcode="5005" errortext="avs_cmpt_out_of_svc" errortime=" " macaddress="" serveripaddress=" " servicegroup=" " sourceeventid=" ::1::1::75::70::4044::112" sessionid="" /> <Error errorcode="5005" errortext="avs_cmpt_out_of_svc" errortime=" " macaddress="" serveripaddress=" " servicegroup=" " sourceeventid=" ::1::1::75::70::4044::113" sessionid="" /> <Error errorcode="5005" errortext="avs_cmpt_out_of_svc" errortime=" " macaddress="" serveripaddress=" " servicegroup=" " sourceeventid=" ::1::1::75::70::4044::114" sessionid="" /> <Error errorcode="5005" errortext="avs_cmpt_out_of_svc" errortime=" " macaddress="" serveripaddress=" " servicegroup=" " sourceeventid=" ::1::1::75::70::4044::115" sessionid="" /> </ErrorsResponse> Devices The Devices request-response message returns a list of the CDS devices. Request Required: Devices Request Example Response One of the following HTTP status codes is returned: 2-7

22 ServiceGroups Chapter 2 Monitoring APIs 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The DevicesResponse element is returned in the XML body response. Table 2-6 describes the XML body elements and attributes returned in the DevicesResponse element. Table 2-6 DevicesResponse Element Attributes Data Types Descriptions Device list element Element that contains the device information. description xs:string Description of the device. hostname xs:string Hostname of the device. ipaddress xs:string IP address of the device. type xs:string Device type (Streamer, Vault, or ISV). Response Example <?xml version="1.0" encoding="utf-8"?> <DevicesResponse xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/devices.xsd"> <Device description="vault" hostname="vault216" ipaddress=" " type="vault" /> <Device description="vault" hostname="vault218" ipaddress=" " type="vault" /> <Device description="vault" hostname="vault219" ipaddress=" " type="vault" /> <Device description="streamer" hostname="stm44" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm74" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm75" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm76" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm77" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm78" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm79" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm81" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm82" ipaddress=" " type="streamer" /> <Device description="streamer" hostname="stm83" ipaddress=" " type="streamer" /> </DevicesResponse> ServiceGroups The ServiceGroups request-response message returns a list of the service groups configured in the CDS. Request Required: ServiceGroups Request Example Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 2-8

23 Chapter 2 Monitoring APIs ContentState 400 Bad Request Request parameters were incomplete or invalid. The ServiceGroupsResponse element is returned in the XML body response. Table 2-7 describes the XML body elements and attributes returned in the ServiceGroupsResponse element. Table 2-7 ServiceGroupsResponse Element Attributes Data Types Descriptions ServiceGroup list element Element that contains the service group information. servicegroup xs:integer Service group configured in the CDS. TSIDOutput xs:integer The associated transport stream identifier (TSID) out port on the Quadrature Amplitude Modulation (QAM) device. 1 bandwidth xs:integer The bandwidth usage of this service group. 1 EdgeDeviceIP xs:string The IP address of the QAM device Only for Asynchronous Serial Interface (ASI) streaming. Response Example The response example is for a CDS configured with Gigabit Ethernet streaming. <?xml version="1.0" encoding="utf-8"?> <ServiceGroupsResponse xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/servicegroups.xsd"> <ServiceGroup servicegroup="21"> <ServiceGroup servicegroup="22"> <ServiceGroup servicegroup="73"> </ServiceGroupsResponse> ContentState The ContentState request-response message returns a list of the content in the CDS. Request Required: ContentState Request Example Response One of the following HTTP status codes is returned. 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The ContentStateResponse element is returned in the XML body response. 2-9

24 ContentState Chapter 2 Monitoring APIs Table 2-8 describes the XML body elements and attributes returned in the ContentStateResponse element. Table 2-8 ContentStateResponse Element Attributes Data Types Descriptions ContentState list element Element that contains the content information. assetior xs:string Interoperable Object Reference (IOR) for the content. contentname xs:string Name of the content. dateingested xs:integer The time (since start of UNIX epoch time) that the content was ingested into the CDS. 1 digestipaddress xs:string The IP address of the Vault that ingested the content. filesize xs:integer The size, in bytes, of the content file. isaadminstate xs:string The administrative state of this content. The possible administrative states are: 1. UNIX epoch time is T00:00:00Z Unprovisioned Content is loading. In Service Content is available for streaming. Out of Service Content is not available for streaming. isaopstate xs:string The operational state of this content. The possible operational states are: Created Content is loading. In Service Content is available for streaming. Out of Service Content is not available for streaming. bitrate xs:integer The rate of ingest in bits per second ( = 3.75 Mbps). assetname xs:string Name used in the ADI metadata for a group of content objects that make up one asset. Response Example <?xml version="1.0" encoding="utf-8"?> <ContentStateResponse dateformat="" xmlns:xsi=" xsi:nonamespaceschemalocation="../../src/xsd/contentstate.xsd"> <ContentState assetior="ior: c3a e e636f6d2f d6f64756c652f a312e c ff0e e32322e39392e a f004e f f796f f d " contentname="nba_sr_michaelvmagic1991-jpw91gb_2.mpg" dateingested=" " digestipaddress=" " filesize=" " isaadminstate="inservice" isaopstate="inservice" bitrate=" " assetname="arroyoasset" /> <ContentState 2-10

25 Chapter 2 Monitoring APIs Version assetior="ior: c3a e e636f6d2f d6f64756c652f a312e c ff0e e32322e39392e a f004e f f796f f d " contentname="nba_sr_michaelvmagic1991-jpw91gb_4.mpg" dateingested=" " digestipaddress=" " filesize=" " isaadminstate="inservice" isaopstate="inservice" bitrate=" " assetname="arroyoasset" /> </ContentStateResponse> Version The Version request-response message returns the version of the API running on the CDS. Request Required: Version Request Example Response One of the following HTTP status codes are returned. 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The APIVersionResponse element is returned in the XML body response. Table 2-9 describes the XML body attributes returned in the APIVersionResponse. Table 2-9 APIVersionResponse Attributes Data Types Descriptions major xs:integer The integer portion of the API version. minor xs:integer The decimal number portion of the API version. Response Example <?xml version="1.0" encoding="utf-8"?> <APIVersionResponse major="1" minor="3" xmlns:xsi=" xsi:nonamespaceschemalocation="..\..\src\xsd\apiversion.xsd"/> 2-11

26 Version Chapter 2 Monitoring APIs 2-12

27 CHAPTER 3 RTSP Stream Diagnostics APIs This chapter describes the format and content of the RTSP stream diagnostic API messages. The Real Time Streaming Protocol (RTSP) API messages are used for RTSP environments and consist of the following: StreamsBySmartcard, page 3-1 GetStreamDetailsBySessionId, page 3-3 GetStreamTrickmodesBySessionId, page 3-4 All HTTP request messages follow the format given in the HTTP Headers section on page 1-2. StreamsBySmartcard The StreamsBySmartcard request-response message returns the streams associated with a specified smart card. A smart card is a unique identifier (ID) that represents a set-top box (STB). Request Element: StreamsBySmartcard Table 3-1 describes the XML attributes for the StreamsBySmartcard request. Table 3-1 StreamsBySmartcard Attributes Data Types Descriptions Smartcard xs:string Unique ID for STB. Starttime xs:integer Stream start time. The time and date is represented in seconds since the start of UNIX epoch time. 1 Endtime xs:integer Stream end time. The time and date is represented in seconds since the start of UNIX epoch time UNIX epoch time is T00:00:00Z Request Example POST /rtsp/sdi?action=streamsbysmartcard HTTP/1.0 User-Agent: HTTPTool/1.0 Content-Type: text/xml Cseq: 123 Content-Length: 128 <?xml version="1.0" encoding="utf-8"?> 3-1

28 StreamsBySmartcard Chapter 3 RTSP Stream Diagnostics APIs <StreamsBySmartcard Smartcard = Starttime = Endtime = /> Note If you do not specify a Starttime and Endtime, all the streams that the STB has sent are listed. The Starttime and Endtime parameters represent the range to use for searching the start time of the streams. The response returns all the streams that have a start time that falls within Starttime and Endtime range. Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The StreamsBySmartcardResponse element is returned in the XML body response. Table 3-2 describes the XML body elements and attributes returned in the StreamsBySmartcardResponse element. Table 3-2 StreamsBySmartcardResponse Element Attributes Data Types Descriptions StreamObject Element Element that contains the stream information. SessionId xs:string Session ID associated with this stream. Content xs:string Name of content. Starttime xs:integer Stream start time (since start of UNIX epoch time). 1 Endtime xs:integer Stream end time (since start of UNIX epoch time) UNIX epoch time is T00:00:00Z Response Example <?xml version="1.0" encoding="utf-8"?> <StreamsBySmartcardResponse> <StreamObject SessionId = Content = aviator.mpg Starttime = Endtime = /> <StreamObject SessionId = Content = looney.mpg Starttime = Endtime = /> </StreamsBySmartcardResponse> 3-2

29 Chapter 3 RTSP Stream Diagnostics APIs GetStreamDetailsBySessionId GetStreamDetailsBySessionId The GetStreamDetailsBySessionId request-response message returns a list of the stream details for a specified session ID. Request Element: GetStreamDetailsBySessionId Attribute: SessionId The SessionId attribute is a string data type. Request Example POST /rtsp/sdi?action=getstreamdetailsbysessionid HTTP/1.0 User-Agent: HTTPTool/1.0 Content-Type: text/xml Cseq: 123 Content-Length: 103 <?xml version="1.0" encoding="utf-8"?> <GetStreamsDetailsBySessionId SessionId = " " /> Response One of the following HTTP status codes is returned: 200 Ok Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The GetStreamDetailsBySessionIdResponse element is returned in the XML body response. Table 3-4 describes the XML body elements and attributes returned in the GetStreamDetailsBySessionIdResponse element. Table 3-3 GetStreamDetailsBySessionIdResponse Element Attributes Data Types Descriptions StreamDetails Element Element that contains the stream details. SessionId xs:string Session ID associated with this stream. Content xs:string Name of content. Starttime xs:integer Stream start time (since start of UNIX epoch time). 1 Endtime xs:integer Stream end time (since start of UNIX epoch time). 1 DestinationIP xs:string Destination IP address for this stream. DestinationPort xs:integer Destination port for this stream. ServiceGroup xs:integer Service Group used to send the stream. AllocatedBandwidth xs:integer Bandwidth allocated, in bits per second, for this stream. 1. UNIX epoch time is T00:00:00Z 3-3

30 GetStreamTrickmodesBySessionId Chapter 3 RTSP Stream Diagnostics APIs Response Example <?xml version="1.0" encoding="utf-8"?> <GetStreamDetailsBySessionIdResponse> <StreamDetails SessionId = " " StartTime = " " EndTime = " " DestinationIP = " " DestinationPort = "8198" ServiceGroup = "1234" AllocatedBandwidth = " " /> </GetStreamDetailsBySessionIdResponse> GetStreamTrickmodesBySessionId The GetStreamTrickmodesBySessionId request-response message returns a list of trick modes for a specified session ID. Request Element: GetStreamTrickmodesBySessionId Attribute: SessionId The SessionId attribute is a string data type. Request Example POST /rtsp/sdi?action=getstreamtrickmodesbysessionid HTTP/1.0 User-Agent: HTTPTool/1.0 Content-Type: text/xml Cseq: 123 Content-Length: 105 <?xml version="1.0" encoding="utf-8"?> <GetStreamTrickmodesBySessionId SessionId = /> Response: One of the following HTTP status codes is returned: 200 OK Request was successful. 400 Bad Request Request parameters were incomplete or invalid. The GetStreamTrickmodesBySessionIdResponse element is returned in the XML body response. Table 3-4 describes the XML body elements and attributes returned in the GetStreamTrickmodesBySessionIdResponse element. 3-4

31 Chapter 3 RTSP Stream Diagnostics APIs GetStreamTrickmodesBySessionId Table 3-4 GetStreamTrickmodesBySessionIdResponse Element Attributes Data Types Descriptions TrickmodeAction list element Element that contains the trick-mode information. ActionTime xs:date-time Coordinated universal time (UTC) time when the trick mode occurred. Date and time are specified in ISO 8601:2000 format. NPTOffset xs:integer Current normal play time (NPT) offset of content in milliseconds. Speed xs:integer Play speed change that occurred at the ActionTime. Response Example: <?xml version="1.0" encoding="utf-8"?> <GetStreamTrickmodesBySessionIdResponse> <TrickmodeList <TrickmodeAction ActionTime = " T23:43:56Z" NPTOffset = "0" Speed = "1" /> </TrickmodeList> </GetStreamTrickmodesBySessionIdResponse> 3-5

32 GetStreamTrickmodesBySessionId Chapter 3 RTSP Stream Diagnostics APIs 3-6