HP-UX Multimedia Streaming Protocols (MSP) Programmer's Guide HP-UX 11i v1, HP-UX 11i v2, HP-UX 11i v3 HP Part Number: 5992-1320 Published: September 2007
© Copyright 2007 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Table of Contents About This Document...................................................................................................................11 Intended Audience.............................................................................................................11 Document Organization.....................................................................................................11 Typographical Conventions.............................................................................
Range Header.....................................................................................................53 RTP-Info Header.................................................................................................55 Transport Header................................................................................................57 RTSP URL APIs........................................................................................................60 RTSP Connection Option APIs...................
The librtsp APIs................................................................................................................107 The librtsp Data Structures...............................................................................................110 The librtsp Enumerated Values........................................................................................111 Index................................................................................................................................
List of Figures 1-1 1-2 2-1 2-2 2-3 2-4 Multimedia Streaming Architecture...........................................................................14 MSP Framework..........................................................................................................15 RTP Call Order Sequence............................................................................................27 RTSP Client-Server Call Order Sequence....................................................................
List of Tables 1-1 1-2 2-1 2-2 2-3 2-4 2-5 2-6 2-7 3-1 3-2 A-1 A-2 A-3 Header Files Shipped with the MSP SDK...................................................................17 Libraries Shipped with the MSP SDK.........................................................................17 The option Values........................................................................................................24 The state Argument Values..........................................................................
About This Document This manual describes how to install and use the HP-UX Multimedia Streaming Protocols (MSP) Software Developer’s Kit (SDK) on the HP-UX 11i v1, HP-UX 11i v2, and HP-UX 11i v3 operating systems. This manual assumes that the HP-UX 11i v1, HP–UX 11i v2, or HP-UX 11i v3 operating system software and the appropriate files, scripts, and subsets are installed. The document printing date and part number indicate the document’s current edition.
Book Title KeyCap Emphasis Emphasis Term ComputerOut UserInput Command Variable [] {} ... | Information CD, it may be a link to the manpage itself. From the HP-UX command line, you can enter “man audit” or “man 5 audit” to view the manpage. See man(1). The title of a book. On the web and on the Instant Information CD, it may be a link to the book itself. The name of a keyboard key. Note that Return and Enter both refer to the same key. Text that is emphasized. Text that is strongly emphasized.
1 Introduction This chapter presents an overview of the Multimedia Streaming Protocols (MSP) Software Developer’s Kit (SDK) and its supported features on your HP-UX 11i v1, HP-UX 11i v2, and HP-UX 11i v3 operating systems. This chapter discusses the following topics: • “MSP Overview” (page 13) • “Files Provided with the MSP SDK” (page 16) MSP Overview MSP enables you to transfer audio and video files to a remote location in real time.
Figure 1-1 Multimedia Streaming Architecture Client Live Broadcast Run Attn. Fault Remote Power Network Stored Content Streaming Server Network Client Multimedia streaming setup, as shown in Figure 1-1, includes two types of interactions. In the server part, the multimedia streaming server accepts multimedia data or input from any of the following sources: • Live broadcast, such as a digital camera connected to the computer port. • Data stored in the form of media.
Figure 1-2 MSP Framework Multimedia Application MSP APIs MSP Suite of Protocols SDP RTSP RTP/RTCP User Space Kernel Space RTP/RTCP Modules Media Control Media Packet TCP UDP Kernel Space Hardware Network Interface The HP-UX MSP framework comprises the following modules: • Real-Time Protocol (RTP) • Real-Time Control Protocol (RTCP) • Real-Time Streaming Protocol (RTSP) • Session Description Protocol (SDP) The MSP framework contains the RTSP and SDP modules in the user space and the RTP and RTCP m
• • Multicast audio conference Audio and video conference For information on RTP APIs, see “RTP Library” (page 19). Real-Time Streaming Protocol RTSP controls the transfer of real-time media data and serves as a network remote control for multimedia services. The client requests a selected media file from the server using RTSP. The server, in response, returns information required by the client to transfer the data. Applications run RTSP on top of TCP.
Table 1-1 Header Files Shipped with the MSP SDK Header File Description /usr/include/rtp.h Specifies the RTP header file. /usr/include/rtsp.h Specifies the RTSP header file. /usr/include/sdp.h Specifies the SDP header file. Libraries Supplied with the SDK for C The MSP SDK for C includes different library sets. The specific library files that you link with depend on the type of application or applications you are building.
2 Using MSP APIs This chapter describes how to use the Application Programming Interfaces (APIs) in the MSP SDK. It discusses the following topics: • “RTP Library” (page 19) • “RTP Call Order Sequence” (page 26) • “RTSP Library” (page 28) • “RTSP Call Order Sequence” (page 63) • “SDP Library” (page 67) • “SDP Call Order Sequence” (page 76) RTP Library This section describes the APIs in the RTP library.
• RTCP control packet APIs The RTP library provides APIs for retrieving control packets from the library. The library automatically generates the control packets and sends them to all the members of the RTP session. The following lists the RTCP control packet APIs: — rtcp_recv — rtcp_free_buf • RTP I/O control option APIs The RTP library provides options for setting and retrieving the members of the active RTP session that can be configured by the application.
— rtp_addr This is a pointer to an IPv4 or IPv6 socket address structure. — rtcp_addr This is a pointer to an IPv4 or IPv6 socket address structure. These arguments point to a structure that specifies the address and port on which RTP and RTCP packets are received. • rtp_close You can use rtp_close to terminate an RTP session, represented by rd, that is obtained by calling rtp_open.
Extension headers use rtp_xtn_hdr_t, a data structure, as follows: /* RTP Extension header */ typedef struct { uint16_t uint16_t char rtp_xtn_hdr_t; profile; len; *hdrp;} The following lists the RTP data packet APIs: • rtp_send You can use this API to send an RTP packet to all the members that an application specifies, using the rtp_ioctl APIs. The declaration of rtp_send is as follows: # include int rtp_send(int rd, rtp_pkt_t *pkt); where pkt is a pointer to the rtp_pkt_t structure.
where buf is the size of the buffer. The return value of rtp_free_buf is not predictable if buf is not valid or not allocated by rtp_recv. RTCP Control Packet APIs This section describes the RTCP control packet APIs that the RTP module includes. The following lists the RTCP control packet APIs: • rtcp_recv You can use rtcp_recv to receive RTCP packets. The declaration of rtcp_recv is as follows: # include
• option The option argument indicates the type of operation to be performed. Each of the options expects one or more arguments. The option argument can take one of the values listed in Table 2-1. Table 2-1 The option Values Value Description RTP_GSSRC (uint32_t *ssrc) Obtains the Synchronization Source (SSRC) identifier. RTP_GMEMCOUNT (uint32_t *ssrc) Obtains the current count of members. RTP_GMEMLIST (char *buf, int buflen) Obtains the current list of members.
Table 2-1 The option Values (continued) Value Description RTP_AMCAST (struct ip_mreq *mreq) Request to join the multicast group to receive multicast RTP packets on the RTP session descriptor. RTCP_AMCAST (struct ip_mreq *mreq) Request to join the multicast group to receive multicast RTCP packets on the RTP session descriptor. For more information, type man 3n rtp_ioctl at the HP-UX command prompt.
• rtcp_parse_pkt The rtcp_parse_pkt API uses rtcp_pkt_t, the RTCP packet data structure that begins with the common header, as follows: typedef struct rtcp_pkt { rtcp_common_t *common; union { struct rtcp_sr *sr; struct rtcp_rr *rr; struct rtcp_sdes *sdes; struct rtcp_app *app; struct rtcp_bye *bye; }rtcp_unit; }; typedef struct rtcp_pkt rtcp_pkt_t; The declaration of rtcp_parse_pkt is as follows: int rtcp_parse_pkt(rtcp_pkt_t **pkt, char *buf, int buflen); where buf contains the RTCP packet that was rec
Figure 2-1 RTP Call Order Sequence rtp_open One or more rtp ioctl interfaces Repoll No Poll for rtp_send (rtp poll) Yes rtp_send rtp_close An application initiates a session for data transport using rtp_open. It may optionally set control options for the session using the rtp_ioctl interface. The control options set the addresses of the participating members for the session using the RTP_SSENDTOADDRLST option through rtp_ioctl.
The RTP library initiates RTCP packets and eliminates the need for an application to initiate the RTCP packet. The library collects and maintains statistics. The library also handles timers for sending RTCP packets. You can receive RTP and RTCP packets using rtp_recv and rtcp_recv, respectively. You can parse the compound RTCP packets by using rtcp_parse_pkt. You can free the resources for the buffers using the corresponding freeing APIs. To close an RTP session, use rtp_close.
For example, rtsp_status_code_str [RTSP_100] is a pointer that points to the location containing the 100 string. • rtsp_status_text This is an array of pointers to locations that contain the RTSP reason phrase strings corresponding to the RTSP status codes. You must index this array using the enumerated RTSP status code. For example, rtsp_status_text [RTSP_100] is a pointer that points to the location containing the string, Continue. The reason phrase corresponding to the status code is 100.
The following lists the APIs that set or retrieve the header information in RTSP messages: — — — — rtsp_set_msg_hdr rtsp_get_msg_hdr rtsp_copy_msg_hdr rtsp_append_msg_hdr The following lists the APIs that set or retrieve the body of RTSP messages: — rtsp_set_msg_body — rtsp_get_msg_body • Header APIs You must specify the header information for most of the header types in the form of strings. However, you may have to define data structures for certain headers.
— RTP-info header The rtsp_rtpinfo_t data structure stores information about the RTP-info header. The RTSP header file, , contains the definition of this data structure. The following lists the RTP-info header APIs: ◦ ◦ ◦ rtsp_init_rtpinfo rtsp_alloc_rtpinfo rtsp_free_rtpinfo — Transport header The rtsp_xport_spec_t data structure stores information about the transport header. The RTSP header file, rtsp.
The following describes the RTSP connection APIs: • rtsp_open To create a new RTSP connection, use rtsp_open. The declaration of rtsp_open is as follows: #include rtsp_error_t rtsp_open( rtsp_url_t *rtspurl, rtsp_flags_t flags, rtsp_conn_t **conn ); The rtsp_open function dynamically allocates memory for a new rtsp_conn_t structure and opens a transport connection to the peer. The rtspurl argument must point to the rtsp_urt_t structure, which contains the peer information.
— RTSP_ESYS System call error. Global variable errno contains the specific error number. — RTSP_ENAMRESOLV Name resolution error. • rtsp_create_conn To create an RTSP connection, use rtsp_create_conn. The declaration of rtsp_create_conn is as follows: #include
• rtsp_recv You can use rtsp_recv to receive an RTSP message or an interleaved media packet from an RTSP connection. The declaration of rtsp_close is as follows: #include rtsp_pckt_type_t rtsp_recv( rtsp_conn_t *conn, void *pckt, int *size, int *channel ); You must pass the following arguments to rtsp_recv: — conn Pointer to a location containing the rtsp_conn_t structure. — pckt Pointer where the location of the received RTSP message or the interleaved media packet is returned.
— RTSP_EINVAL ◦ The pckt argument does not contain a SOCK_STREAM socket. ◦ The conn argument is NULL. ◦ The size argument is required and is NULL. ◦ The channel argument is required and is NULL. — RTSP_ENOBUFS No buffer space to accommodate the received data. — RTSP_ENOMEM Dynamic memory allocation failure. — RTSP_ECONNABORTED The RTSP connection was closed by the peer. — RTSP_ESYS System call error. Global variable errno contains the specific error number.
RTSP Session APIs The RTSP session data structure encapsulates all the necessary information about an RTSP session, such as the session URL, session ID and the state of the session. The udata member of this structure stores the session data that is specific to the application. The rtsp.h file contains the definition of the rtsp_session_t data structure.
more information on creating an association between session and connection, see “RTSP Connection Option APIs” (page 61). The following lists the RTSP session APIs: • rtsp_init_session You can use rtsp_init_session to initialize the members of the rtsp_session_t structure with the arguments supplied by the application. The declaration of rtsp_init_session is as follows: #include
You must pass session, a pointer to an rtsp_session_t structure as an argument to rtsp_free_session_flds. The rtsp_free_session_flds API does not return a value. For more information, type man 3 rtsp_free_session_flds at the HP-UX command prompt. • rtsp_free_session You can use rtsp_free_session to free the dynamically allocated memory for the rtsp_session_t structure and its members. The declaration of rtsp_free_session is as follows: #include
Table 2-3 Method Values Method Description RTSP_DESCRIBE DESCRIBE request message. RTSP_ANNOUNCE ANNOUNCE request message. RTSP_GET_PARAMETER GET_PARAMETER request message. RTSP_OPTIONS OPTIONS request message. RTSP_PAUSE PAUSE request message. RTSP_PLAY PLAY request message. RTSP_RECORD RECORD request message. RTSP_REDIRECT REDIRECT request message. RTSP_SETUP SETUP request message. RTSP_SET_PARAMETER SET_PARAMETER request message. RTSP_TEARDOWN TEARDOWN request message.
The rtsp_init_response_msg function dynamically allocates memory for the rtsp_msg_t structure and sets the status code and the reason phrase in the message to the specified values. The declaration of rtsp_init_response_msg is as follows: #include rtsp_error_t rtsp_init_response_msg( int status_code, uint8_t *reason_phrase, rtsp_msg_t *req_msg, rtsp_msg_t **msg ); You must pass the following arguments to rtsp_init_response_msg: — status_code Integer status code to be set in the message.
For more information, type man 3 rtsp_init_response_msg at the HP-UX command prompt. • rtsp_is_request_msg and rtsp_is_response_msg You can use rtsp_is_request_msg and rtsp_is_response_msg functions to examine if an RTSP message is a request message or a response message, respectively. The declarations of these APIs are as follows: #include
char *url ); You must pass the following arguments to rtsp_set_msg_request_line: — msg Pointer to a location containing an RTSP request message. — method Enumerated RTSP method type. See Table 2-3 (page 39) for information on method types. — url Pointer to a location containing the NULL URL string. Upon success, rtsp_set_msg_request_line returns RTSP_SUCCESS; upon failure, it returns one of the following error values: — RTSP_EINVAL ◦ The msg argument is NULL. ◦ The url argument is NULL.
— msg Pointer to a location containing an RTSP request message. — url Pointer to a location where the URL in the message is returned. — len Length, in bytes, of the location pointed by the url argument. Upon success, rtsp_get_msg_request_line returns the method of the RTSP message in the form of an enumerated method code; upon failure, it returns RTSP_EINVAL in any of the following cases: — The msg argument is NULL. — The url argument is not NULL and the len argument contains an invalid value.
Upon success, rtsp_set_msg_response_line returns RTSP_SUCCESS; upon failure, rtsp_set_msg_response_line returns one of the following error values: — RTSP_EINVAL ◦ The msg argument is NULL. ◦ The status argument contains an invalid status code. ◦ The location pointed to by the msg argument does not contain a response message. — RTSP_ENOMEM Dynamic memory allocation failure. For more information, type man 3 rtsp_set_msg_response_line at the HP-UX command prompt.
For more information, type man 3 rtsp_get_msg_response_line at the HP-UX command prompt. Header Information APIs You can use the following APIs to set, modify, and retrieve header information in RTSP messages: • rtsp_set_msg_hdr You can use rtsp_set_msg_hdr to set the header field in an RTSP message. The declaration of rtsp_set_msg_hdr is as follows: #include
Upon success, the rtsp_set_msg_hdr function returns RTSP_SUCCESS; upon failure, rtsp_set_msg_hdr returns one of the following error values: — RTSP_EINVAL ◦ The msg argument is NULL. ◦ The value contained in the location pointed to by the value argument is invalid. ◦ The value contained in the size argument is invalid. — RTSP_EINVHDR ◦ Value contained in the hdr_type argument is not a valid enumerated RTSP header type.
— value Pointer to a location where the value for the header field is returned. — size Pointer to a location containing the size (in bytes) of the location pointed to by the value argument. Upon success, rtsp_get_msg_hdr returns one of the following values: — RTSP_SUCCESS Successful completion. The location pointed to by the value argument stores header information. — RTSP_HDR_NOT_IN_MSG The RTSP message does not contain the header indicated by the hdr_type argument.
You must pass the following arguments to rtsp_copy_msg_hdr: — dst_msg Pointer to a location containing the rtsp_msg_t structure. — src_msg Pointer to a location containing the rtsp_msg_t structure. — hdr_type Enumerated RTSP header field type. Upon success, the existing information for the header in dst_msg is overwritten with the header information from src_msg.
— value Pointer to a location containing the value for the header field. — size Size (in bytes) of the location pointed to by the value argument. Upon success, rtsp_append_msg_hdr returns RTSP_SUCCESS; upon failure, it returns one of the following error values: • RTSP_EINVAL — The msg argument is NULL. — The value contained in the location pointed to by the value argument is invalid. — The value contained in the size argument is invalid.
— msg Pointer to a location containing the rtsp_msg_t structure. — body Pointer to a location containing the body of the RTSP message. — content_len Length, in bytes, of the message body. The rtsp_set_msg_body function overwrites the body of an RTSP message with the specified value and sets the content length header in the RTSP message to the value specified by the content_len argument.
— msg Pointer to a location containing the rtsp_msg_t structure. — body Pointer to a location where the body of the RTSP message is returned. — content_len Pointer to a location containing the size of the location pointed to by the body argument. Ensure that the location pointed to by the content_len argument contains the size of the buffer in the location pointed to by the body argument before calling rtsp_get_msg_body.
typedef struct rtsp_cache { int32_t int32_t uint8_t uint16_t struct rtsp_cache directive:8; seconds:24; *cache_ext; cache_ext_len; *next; } rtsp_cache_t; The directive structure member in the rtsp_cache_t structure contains the cache directive and takes one of the following values: • RTSP_CACHE_NONE • RTSP_CACHE_MAX_STALE • RTSP_CACHE_NO_CACHE • RTSP_CACHE_MIN_FRESH • RTSP_CACHE_ONLYIF_CACHED • RTSP_CACHE_PUBLIC • RTSP_CACHE_PRIVATE • RTSP_CACHE_NO_TRANSFORM • RTSP_CACHE_MUST_REVAL • RTSP_CACHE_PROXY • R
For more information, type man 3 rtsp_init_cache at the HP-UX command prompt. • rtsp_alloc_cache You can use rtsp_alloc_cache to dynamically allocate memory for the rtsp_cache_t structure and to initialize the structure members with application-specific values. The declaration of rtsp_alloc_cache is as follows: #include rtsp_cache_t *rtsp_alloc_cache( rtsp_cache_t *cache2dup ); You must pass cache2dup, a pointer to the rtsp_cache_t structure, as an argument to rtsp_alloc_cache.
The definition of the rtsp_range_t data structure is as follows: typedef struct rtsp_range { uint8_t range_type; uint8_t range_flag; union { struct { rtsp_npt_t start; rtsp_npt_t end; } npt; struct { rtsp_utc_t start; rtsp_utc_t end; } utc; struct { rtsp_smpte_t start; rtsp_smpte_t end; } smpte; } range; struct rtsp_range *next; } rtsp_range_t; The range_type structure member identifies the type of timestamp.
The rtsp_init_range function does not return a value. For more information, type man 3 rtsp_init_range at the HP-UX command prompt. • rtsp_alloc_range You can use rtsp_alloc_range to dynamically allocate memory for the rtsp_range_t structure and to initialize its members with application-specific values. The declaration of rtsp_alloc_range is as follows: #include
int64_t rtptime; struct rtsp_rtpinfo *next; } rtsp_rtpinfo_t; The url member of the rtsp_rtpinfo_t structure is a pointer to the location containing the stream URL specified in the RTP-info header. The seq member of the structure contains the sequence number and the rtptime member contains the RTP timestamp specified in the RTP-info header.
For more information, type man 3 rtsp_alloc_rtpinfo at the HP-UX command prompt. • rtsp_free_rtpinfo You can use rtsp_free_rtpinfo to free the dynamically allocated memory for the rtsp_rtpinfo_t structure and its members. The declaration of rtsp_free_rtpinfo is as follows: #include void rtsp_free_rtpinfo( rtsp_rtpinfo_t *rtpinfo ); You must pass rtpinfo2dup, a pointer to the rtsp_rtpinfo_t structure to be freed, as an argument to rtsp_free_rtpinfo.
struct rtsp_xport_spec *next; } rtsp_xport_spec_t; The xport_id structure member points to a location that contains the transport specifier in the form transport/profile/lower-transport. The src_addr and dest_addr structure members are pointers to the locations that contain the source and destination address parameters in the transport specifier. The channel_start and channel_end structure members contain the range of the interleaved transport specifier parameter.
For more information, type man 3 rtsp_init_xport_spec at the HP-UX command prompt. • rtsp_alloc_xport_spec You can use rtsp_alloc_xport_spec to dynamically allocate memory for rtsp_xport_spec_t structure and to initialize its members with application-specific values. The declaration of rtsp_alloc_xport_spec is as follows: #include
void rtsp_free_xport_spec_flds( rtsp_xport_spec_t *xport_spec ); You must pass xport_spec, a pointer to the rtsp_xport_spec_t structure, as an argument to rtsp_free_xport_spec_flds. The rtsp_free_xport_spec_flds function does not return a value. For more information, type man 3 rtsp_free_xport_spec_flds at the HP-UX command prompt. RTSP URL APIs The RTSP URL data structure, rtsp_url_t, stores information about the RTSP URL, such as the protocol being used, host, port, and absolute path.
You must pass the following arguments to rtsp_parse_url: • url Pointer to a location containing a string in RFC 2326 RTSP URL format. • rtspurl Pointer to a location containing the rtsp_url_t structure. Upon success, rtsp_parse_url returns RTSP_SUCCESS and the parsed URL is stored in the location pointed to by the rtspurl argument. Upon failure, it returns one of the following error values: • RTSP_EINVAL — The url argument is NULL. — The rtspurl argument is NULL.
You must pass the following arguments to rtsp_set_conn_opt: — conn RTSP connection for which the option is being set. — opt_type Parameter that identifies the option being set. — opt_value Pointer to a location containing the value of the option. — opt_size Size of the data structure in the location pointed to by opt_value. Upon success, rtsp_set_conn_opt returns RTSP_SUCCESS. Upon failure, it returns RTSP_EINVAL in any of the following cases: — RTSP_EINVAL ◦ The conn argument is NULL.
— opt_value Pointer to a location where the value of the option is returned. — opt_size Pointer to a location that contains the size, in bytes, of the data structure present in the location pointed to by opt_value. You can retrieve the following options associated with an RTSP connection: — RTSP_OPT_SOCKET (int *) retrieves the socket descriptor for the RTSP connection. The opt_size argument is ignored and is not updated on return.
3. 4. 5. 6. 7. 8. 9. Use the rtsp_set_msg_hdr API to set the RTSP header information in the message. The application sends an RTSP message, identified by the rtsp_msg_t structure, using the rtsp_send_msg API. Receive the RTSP messages using rtsp_recv. To identify the message type (request or response message), use the rtsp_is_request_msg and the rtsp_is_response_msg APIs. Retrieve the request or response line information of a message using rtsp_get_msg_request_line and rtsp_get_msg_response_line.
NOTE: After calling rtsp_free_msg, do not use msg again without a call to (1) in the previous list. • For rtsp_conn_t, call either rtsp_open or rtsp_create_conn before calling APIs that require arguments of type rtsp_conn_t *. In other words, you must obtain the rtsp_conn_t* data structure only from rtsp_open or rtsp_create_conn. After calling rtsp_close, you must not reference the memory location passed to the rtsp_close. The call sequence with respect to rtsp_conn_t structure is as follows: 1.
NOTE: If you use rtsp_*_t structures as OUT arguments to APIs, or the API allocates memory and initializes the structures, you do not need to call the initialization functions for the structures. You may not have to do the first step in the previous sequence.
Figure 2-2 RTSP Client-Server Call Order Sequence Typical Client Typical Server Socket Operations rtsp_open() rtsp_create_conn() rtsp_init_request_msg () rtsp_recv() rtsp_send_msg() rtsp_get_msg_hdr() rtsp_free_msg() rtsp_free_msg() rtsp_recv() rtsp_init_response_ msg() rtsp_get_msg_hdr() rtsp_set_msg_hdr() rtsp_get_msg_body() rtsp_set_msg_body() rtsp_free_msg() rtsp_close() rtsp_send_msg() rtsp_free_msg() rtsp_close() SDP Library The following lists the types of descriptions included in a real
• Session description The session description includes the elements listed in Table 2-4. Table 2-4 SDP Session Description • Notation Description v Protocol version. o Session owner. s Session name. i Session information. e E-mail address. c Connection information. b Bandwidth information. u URI of description. p Phone number. z Time zone adjustments. a Session attributes. k Encryption key.
SDP APIs The APIs included in the SDP library have the following functions: • “Parsing the Buffer and Filling Up the SDP Structure” (page 69) • “Generating an SDP Packet from the SDP Structure” (page 69) • “Obtaining or Setting SDP Structure Members” (page 70) • “Obtaining or Adding the Structure Members for Media Descriptions” (page 74) • “Initializing the SDP Structure and Allocating Space” (page 75) • “Freeing the Space Allocated for the SDP Structure” (page 76) • “Creating an SDP Packet” (page 76) • “Pa
The sdp_create_buf API generates an SDP packet from the SDP structure that is created using sdp_parse_buf. For more information, type man 3 sdp_create_buf at the HP-UX command prompt. Return Values Upon success, sdp_create_buf returns SDP_SUCCESS; upon failure, it returns one of the following error values: • SDP_EPROT Non-RFC compliant description string encountered. • SDP_EEOF EOF/end of buffer reached while parsing. • SDP_ENOMEM Memory allocation failure. • SDP_EBUFOVFLW Buffer overflow encountered.
sdp_adj_time_list_t *sdp_get_tzoneadjust(sdp_t *sdp); sdp_encr_key_t *sdp_get_encrkey(sdp_t *sdp); sdp_attribute_list_t *sdp_get_attribute(sdp_t *sdp); int sdp_add_connection(sdp_t *sdp, char *nettype, char *addrtype, char *addr, char *ttl, char *no_of_addr); int sdp_add_bandwidth(sdp_t *sdp, char *bwtype, char *bandwidth); int sdp_add_attribute(sdp_t *sdp, char *att_name, char *att_value); int sdp_add_time(sdp_t *sdp, char *start, char *stop, char *interval, char *a ct_dur, char *offset); int sdp_add_tzone
Table 2-6 The sdp_get and sdp_add APIs (continued) 72 API Description sdp_add_uri() Adds Universal Resource Identifier (URI) information to the SDP structure. Usually, a URI is a pointer to additional information about the conference. The uri argument points to this information. sdp_add_email() Adds the e-mail address of the contact person responsible for the conference. email points to the e-mail address to be set. sdp_add_phone() Adds the phone number of the person responsible for the conference.
Table 2-6 The sdp_get and sdp_add APIs (continued) API Description sdp_add_tzoneadjust() Adds time zone adjustment information. The adjtime and offset arguments point to the adjust time and the offset, respectively. sdp_add_encrkey() Adds encryption key information. The key_method and key_data arguments point to the encryption method (mechanism used for obtaining a usable key) and the encryption key, respectively.
Obtaining or Adding the Structure Members for Media Descriptions The SDP header file, sdp.h, contains the declarations of sdp_get_media* and sdp_add_media* APIs as follows: #include
Table 2-7 The sdp_get_media* and sdp_add_media* APIs (continued) API Description sdp_add_media_title() Adds media title information. The i_info argument points to the media title. sdp_add_media_connection() Adds connection information for media.The nettype, addrtype, addr, ttl, and no_of_addr arguments point to network type (IN), address type (IP4 or IP6), base multicast address, time to live (TTL), and the number of addresses, respectively.
typedef struct { char *v_version; /* v= protocol version */ sdp_owner_t *owner_info; /* o= owner/creator info */ char *s_name; /* s= session name */ char *i_info; /* i= session information */ char *u_uri; /* u= uri */ sdp_email_list_t *email; /* e= email address */ sdp_phone_list_t *phone; /* p= phone number */ sdp_connection_list_t *conn_info; /* c= connection info */ sdp_bandwidth_t *bandw_info; /* b= bandwidth */ sdp_time_list_t *ses_time; /* t= time description */ sdp_adj_time_list_t *adj_time; /* z= ti
1. Initiate sdp_t, the SDP structure. sdp_init 2. Fill up sdp_t using sdp_add* APIs. or Fill up sdp_t by parsing an input buffer containing SDP descriptions. sdp_parse_buf 3. Create buffer. sdp_create_buf 4. Free the buffer. sdp_free Figure 2-3 illustrates the call order sequence of APIs that create an SDP packet.
Figure 2-3 Creating an SDP Packet sdp_init() Initialize sdp_t, the sdp structure Yes Want to add elements to sdp_t using APIs? No sdp_parse_buf() Parse an input buffer containing SDP descriptions and Fill up sdp_t sdp_add*() Add elements to sdp_t sdp_create_buf() Create SDP packet from sdp_t Process/use the SDP packet sdp_free() Free the sdp structure Parsing an SDP Packet Figure 2-4 illustrates the call order sequence of APIs that parse an SDP packet.
Figure 2-4 Parsing an SDP Packet sdp_init() Initialize sdp_t, the sdp structure sdp_parse_buf() Parse an input buffer containing SDP descriptions and Fill up sdp_t sdp_get*() Read the required elements of sdp_t Process/use the SDP packet sdp_free() Free the sdp structure SDP Call Order Sequence 79
3 Troubleshooting MSP This chapter describes how to troubleshoot the APIs that the Multimedia Streaming Protocols (MSP) Software Developer’s Kit (SDK) includes. It discusses the following topics: • “Troubleshooting RTP” (page 81) • “Troubleshooting RTSP” (page 82) • “Troubleshooting SDP” (page 83) Troubleshooting RTP Table 3-1 describes how to troubleshoot Real-Time Protocol (RTP) suite of APIs.
Table 3-1 RTP Troubleshooting Tips (continued) API Scenario Tips rtp_send The rtp_send API does not send packets to the other side. The descriptor is valid and correct. It also does not return errors. At least one successful call to rtp_ioctl for RTP_SSENDTOADDR should be made on a valid RTP descriptor before rtp_send can send packets to the other side.
Table 3-2 RTSP Troubleshooting Tips API Scenario Tips rtsp_get_msg_hdr Using the address of an array when a The following is invalid: char ** expected as an argument. rtsp_get_msg_hdr(msg, RTSP_USER_AGENT_HDR, &arr, Example: &size); char arr[10]; int size=10; Instead, use the following: char **ptr = &arr; rtsp_get_msg_hdr(msg, RTSP_USER_AGENT_HDR, ptr, &size); All rtsp_free APIs Calling rtsp_free_* APIs with an argument whose memory is not dynamically allocated.
The sdp_create_buf API may dump core the application if a wrong pointer to the API is passed, as in the following cases: • • • The sdp_create_buf is called before allocating the first argument sdp using sdp_init, and filling up using sdp_add* routines. *sdp_buf == NULL, sdp_create_buf allocates the buffer using malloc, which needs to be freed by free. If *sdp_buf!= NULL, the caller needs to allocate and free the buffer. In this case, *bufsize should contain the maximum size of the buffer.
4 Sample Programs This chapter contains sample programs for RTP, RTSP, and SDP. It includes the following sections: • “RTP Sample Program” (page 85) • “RTSP Sample Program” (page 92) • “SDP Sample Program” (page 104) RTP Sample Program This section includes the following sample programs for RTP: • sender.c When the user requests, the sender.c program sends an RTP packet. • recver.c When the user requests, the recver.c program polls for an RTP packet and receives the packet.
* This Application uses the interfaces provided by the * RTP library to transmit data * */ /* Macros for handling time as double */ #define tv2dbl(tv) ((tv).tv_sec + (tv).tv_usec / 1000000.0) #define dbl2prnt(x) ((int)((long)(x))) ,((int)(((int)(1000000.
} RTCPport = RTPport + 1; addr[0].sin_family=AF_INET; inet_pton(AF_INET,caddr,&addr[0].sin_addr.s_addr); addr[0].sin_port=RTPport; addr[1].sin_family=AF_INET; inet_pton(AF_INET,caddr,&addr[1].sin_addr.s_addr); addr[1].sin_port=RTCPport; rd = rtp_open((char*)addr, (char*)(addr+1)); if(rd>0) { printf(“ tOpened RTP descriptor %d n” “ tReceiving RTP packets on port %d n” “ tand RTCP packets on port %d n” ,rd ,addr[0].sin_port ,addr[1].
); /* * constructing an RTP packet * The RTP packet which we construct does not contain * actual media data, but contains alphabets. * Media streaming applications would replace this * with actual media packets. */ rtp_pkt_t pkt ; pkt.v=2; pkt.p=0; pkt.x=0; pkt.cc=0; pkt.m=1; pkt.pt=7; pkt.seq=1; struct timeval tv; struct timezone tzp; gettimeofday(&tv,&tzp); pkt.ts=tv2dbl(tv); pkt.csrcp=0; pkt.xtnhdrp=0; pkt.datap=(char*)malloc(9); strcpy(pkt.datap,”abcdefgh”,8); pkt.
#include #include /* * This Application uses the interfaces provided by the * RTP library to transmit data * */ /* Macros for handling time as double */ #define tv2dbl(tv) ((tv).tv_sec + (tv).tv_usec / 1000000.0) #define dbl2prnt(x) ((int)((long)(x))) ,((int)(((int)(1000000.
default: { Usage(argv[1]); exit(1); } } } RTCPport = RTPport + 1; addr[0].sin_family=AF_INET; inet_pton(AF_INET,caddr,&addr[0].sin_addr.s_addr); addr[0].sin_port=RTPport; addr[1].sin_family=AF_INET; inet_pton(AF_INET,caddr,&addr[1].sin_addr.s_addr); addr[1].sin_port=RTCPport; rd = rtp_open((char*)addr, (char*)(addr+1)); if(rd>0) { printf(“ tOpened RTP descriptor %d n” “ tReceiving RTP packets on port %d n” “ tand RTCP packets on port %d n” ,rd ,addr[0].sin_port ,addr[1].
} else printf(“ tDestination %s:%d addded to RTCP SENDTO list n” ,destaddr ,remRTCPport ); /* * The library automatically generates RTCP packets. */ /* poll for an RTP packet */ printf(“polling for an RTP packet... n”); rfds[0].rd=rd; rfds[0].
Make File The make file for RTP is as follows: all : sender recver sender: sender.c cc -O sender.c -o sender -l rtp recver: recver.c cc -O recver.c -o recver -l rtp Compiling the Sample RTP Program This section describes how to compile the sample RTP program. Before compiling the program, ensure that the rtp.h header file and the librtp library that come with HP-UX MSP are available on the machine. The rtp.
rtsp_error_t rtsp_conn_t rtsp_url_t err; *rtspconn = NULL; rtspurl; /* Parse the url string and fill up rtspurl */ err = rtsp_parse_url(mediaurl, &rtspurl); if( err!=RTSP_SUCCESS ) { printf(“Error parsing media url %s n”, mediaurl); return rtspconn; } printf(“Connecting to server ...
* rtspconn => The RTSP Connection over which messages * are sent and received. * */ /* * process_describe : * Creates and sends a DESCRIBE Request message to the * server. Receives and processes the response message.
err = rtsp_get_msg_hdr(rspmsg, RTSP_CONTENT_LENGTH_HDR, &sdpbuflen, NULL); if( err!=RTSP_SUCCESS ) { rtsp_free_msg(rspmsg); return err; } /* Allocate a buffer to hold the message body * (i.
char int *sessionid; sessionidlen; /* Create a SETUP RTSP Request Message */ err = rtsp_init_request_msg(RTSP_SETUP, setupurl, &reqmsg); if( err!=RTSP_SUCCESS ) return err; /* Initialize and fill up the Transport Header */ rtsp_init_xport_spec(&xspec); xspec.xport_id = (uint8_t *)”RTP/AVP”; xspec.ncast = RTSP_TRANSMIT_UNICAST; xspec.cport.rtp = crtpport; xspec.cport.
printf(“ nServer RTP and RTCP ports are %d %d n”, (int)serverxspec->sport.rtp, (int)serverxspec->sport.rtcp); /* Free the resources allocated to the entire linked * list of rtsp_xport_spec_t structures */ rtsp_free_xport_spec(serverxspec); /* Retrieve Session Header information from message */ err = rtsp_get_msg_hdr(rspmsg, RTSP_SESSION_HDR, &sessionid, &sessionidlen); if( err!=RTSP_SUCCESS ) { rtsp_free_msg(rspmsg); return err; } printf(“Session ID is %.
/* Check for rtsp_send_msg errors */ if( err<0 ) return err; /* Receive the response for the request Message. We pass * NULL for channel and size argument since we are sure we * would be receiving only a RTSP Message and not an * interleaved media stream.
printf(“ n”); } /* Free the resources allocated to the entire linked * list of rtsp_rtpinfo_t structures */ rtsp_free_rtpinfo(rtpinfo); /* Free the resources allocated for the Response Message */ rtsp_free_msg(rspmsg); return RTSP_SUCCESS; } /* * process_pause : * Creates and sends a PAUSE Request message to the * server. Receives and process the response message.
/* Get the status code of the Response Message */ statuscode = rtsp_get_msg_response_line(rspmsg, NULL, NULL); if( statuscode!=200 ) { rtsp_free_msg(rspmsg); return err; } /* Free the resources allocated for the Response Message */ rtsp_free_msg(rspmsg); printf(“ nPAUSE Succeeded n”); return RTSP_SUCCESS; } /* * process_teardown : * Creates and sends a TEARDOWN Request message to the * server. Receives and processes the response message for * TEARDOWN.
*/ err = rtsp_recv(rtspconn, &rspmsg, NULL, NULL); if( err<0 ) return err; /* Get the status code of the Response Message */ statuscode = rtsp_get_msg_response_line(rspmsg, NULL, NULL); if( statuscode!=200 ) { rtsp_free_msg(rspmsg); return err; } /* Free the resources allocated for the Response Message */ rtsp_free_msg(rspmsg); printf(“ nTEARDOWN Succeeded n”); return RTSP_SUCCESS; } main(int argc, char *argv[]) { /* * mediaurl points to the url passed as a * command-line argument to the program */ char *me
int setupurllen; /* * The mthd variable will hold the enumerated RTSP * Method type for the Method chosen by the user */ rtsp_method_t mthd; int close=0; if( argc!=2 ) { printf(“Usage : %s n”, argv[0]); exit(-1); } mediaurl = argv[1]; /* Connect to the server specified by the mediaurl */ rtspconn = connect2server(mediaurl); if( rtspconn==NULL ) exit(-1); do { display_msg_menu(); scanf(“%d”, &msgcode); switch(msgcode) { case 1: mthd = RTSP_DESCRIBE; err = process_describe(rtspconn, mediaurl);
break; case 4: mthd = RTSP_PAUSE; err = process_pause(rtspconn, mediaurl); break; case 5: mthd = RTSP_TEARDOWN; err = process_teardown(rtspconn, mediaurl); close = 1; break; case 6: close = 1; err = RTSP_SUCCESS; break; default: err = RTSP_SUCCESS; printf(“Invalid value n”); break; } /* * The rtsp_methods array contains the strings for RTSP * Methods.
Compiling the Sample RTSP Program This section describes how to compile the sample RTSP program. Before compiling the program, enure that the rtsp.h header file and the librtsp library provided by the HP-UX MSP suite are available on the machine. The rtsp.h header file is assumed to be in the /usr/include directory and the librtsp library in the /usr/lib directory.To compile, issue the following command: $ cc sampleclient.
void print_session_level_fields(sdp_t *sdp) { sdp_email_list_t *semail; printf(“ nSession Name: %s n”, sdp->s_name); printf(“Session Information: %s n”, sdp->i_info); semail = sdp->email; printf(“Email: “); if (semail != NULL) { do { printf(“%s n”, semail->e_email); semail = semail->next; } while (semail != NULL); } printf(“URI: %s n n”, sdp->u_uri); return; } void print_media_descriptions(sdp_t *sdp) { sdp_media_list_t *mdes; mdes = sdp->media_des; if (mdes != NULL) { do { printf(“Media Title: %s n”, mdes-
media_attr = media_attr->next; } while(media_attr != NULL); } mdes = mdes->next; } return streamct; } Sample Output A sample output of the SDP program is as follows: v=0 o=mhandley 2890844526 2890842807 IN IP4 126.16.64.4 s=SDP Seminar i=A Seminar on the session description protocol u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps e=mjh@isi.edu (Mark Handley) c=IN IP4 224.2.17.
A The librtsp Summary This appendix presents a summary of the Real Time Streaming Protocol (RTSP) library that the Multimedia Streaming Protocol (MSP) Software Developer’s Kit (SDK) includes. The appendix contains the following sections: • “The librtsp APIs” (page 107) • “The librtsp Data Structures” (page 110) • “The librtsp Enumerated Values” (page 111) The librtsp APIs Table A-1 lists and describes the librtsp APIs that the RTSP library provides.
Table A-1 The librtsp APIs (continued) API Description rtsp_init_response_msg Creates a new rtsp_msg_t structure and sets the RTSP status code and reason phrase information. rtsp_free_msg Frees the memory allocated for the rtsp_msg_t structure and its members. Message Type rtsp_is_request_msg Checks if the rtsp_msg_t structure represents an RTSP request message. rtsp_is_response_msg Checks if the rtsp_msg_t structure represents an RTSP response message.
Table A-1 The librtsp APIs (continued) API Description rtsp_get_msg_body Gets message body from the rtsp_msg_t structure. Message Send/Receive rtsp_send_msg Sends an RTSP message over an RTSP connection. rtsp_send_stream Sends interleaved binary data over an RTSP connection. rtsp_recv Receives either an RTSP message or interleaved data from an RTSP connection. Cache Control Header rtsp_init_cache Initializes the members of the rtsp_cache_t structure.
Table A-1 The librtsp APIs (continued) API Description rtsp_init_xport_spec Initializes the members of the rtsp_xport_spec_t structure. rtsp_alloc_xport_spec Creates a new rtsp_xport_spec_t structure and initializes the structure members. rtsp_free_xport_spec_flds Frees the memory allocated for the rtsp_xport_xpec_t structure members. rtsp_free_xport_spec Frees the memory allocated for the entire linked list of rtsp_xport_spec_t structures and their members.
Table A-2 The librtsp Data Structures (continued) Data Structure Description rtsp_methods Array of RTSP method strings. rtsp_hdrs Array of RTSP header field strings. rtsp_status_code Array of RTSP status code integers. rtsp_status_code_str Array of RTSP status code strings. rtsp_status_text Array of RTSP reason phrase strings. The librtsp Enumerated Values Table A-3 lists and describes the enumerated values that the RTSP library uses.
Table A-3 The librtsp Enumerated Values (continued) Value Description RTSP_RANGE_TIME Range ‘time’ specifier in UTC format. Cache Directives RTSP_CACHE_NO_CACHE no-cache directive. RTSP_CACHE_MAX_STALE max-stale directive. RTSP_CACHE_MIN_FRESH min-fresh directive. RTSP_CACHE_ONLYIF_CACHEDS only-if-cached directive. RTSP_CACHE_PUBLIC public directive. RTSP_CACHE_PRIVATE private directive. RTSP_CACHE_NO_TRANSFORM no-transform directive. RTSP_CACHE_MUST_REVAL must-revalidate directive.
Table A-3 The librtsp Enumerated Values (continued) Value Description RTSP_ALLOW_HDR Allow header. RTSP_AUTHORIZATION_HDR Authorization header. RTSP_BANDWIDTH_HDR Bandwidth header. RTSP_BLOCKSIZE_HDR Blocksize header. RTSP_CACHE_CONTROL_HDR Cache control header. RTSP_CONNECTION_HDR Connection header. RTSP_CONTENT_BASE_HDR Content-base header. RTSP_CONTENT_ENCODING_HDR Content-encoding header. RTSP_CONTENT_LANGUAGE_HDR Content-language header.
Table A-3 The librtsp Enumerated Values (continued) 114 Value Description RTSP_SCALE_HDR Scale header. RTSP_SESSION_HDR Session header. RTSP_SERVER_HDR Server header. RTSP_SPEED_HDR Speed header. RTSP_SUPPORTED_HDR Supported header. RTSP_TIMESTAMP_HDR Timestamp header. RTSP_TRANSPORT_HDR Transport header. RTSP_UNSUPPORTED_HDR Unsupported header. RTSP_USER_AGENT_HDR User-agent header. RTSP_VARY_HDR Vary header. RTSP_VIA_HDR Via header.
Index 115
