HP-UX Java SIP Stack Programmer's Guide HP-UX 11i v3 HP Part Number: 5992-4080 Published: February 2008 Edition: 1
© Copyright 2007–2008 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.............................................................................
JSR32 Factories..............................................................................................................41 HP-UX JSR32 Features........................................................................................................42 Event Notification.........................................................................................................42 The REFER Method.......................................................................................................
List of Figures 1-1 1-2 1-3 1-4 2-1 SIP Protocol Structure.................................................................................................21 Establishing and Terminating a Call...........................................................................30 Call Setup Using a Proxy server..................................................................................31 Call Setup Using a Redirect Server.............................................................................
List of Tables 1-1 1-2 1-3 2-1 5-1 Response Types...........................................................................................................25 Specific Response Types..............................................................................................26 Message Parts..............................................................................................................29 SIP Stack Parameters......................................................................................
List of Examples 3-1 3-2 3-3 4-1 4-2 Setting the TRACE_LEVEL Stack Parameter..............................................................52 Sample Method for Creating a Listening Point..........................................................52 Creating a SipProvider................................................................................................52 Compiling an Application...........................................................................................55 Running an Application....
About This Document This document discuses the Session Initiation Protocol (SIP) and the Java™ Specification Request 32 (JSR32) APIs. It describes how to create, compile, and run applications that use the JSR32 APIs on systems running HP-UX 11i v3. It also describes how to troubleshoot exceptions raised by the JSR32 APIs. In addition to the Java SIP stack, the HP implementation of SIP is also available on the C SIP stack.
Typographical Conventions This document uses the following typographical conventions: audit(5) An HP-UX manpage. The name of the manpage is audit and 5 is the section in the HP-UX Reference. On the web and on the Instant 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). Book Title The title of a book. On the web and on the Instant Information CD, it may be a link to the book itself.
• HP-UX C SIP Stack Message Layer Reference Guide at: http://docs.hp.com/en/netcom.html • Request for Comments (RFC) documents: — RFC 1951 (DEFLATE Compressed Data Format version 1.3) http://www.ietf.org/rfc/rfc1951.txt?number=1951 — RFC 2052 (A DNS RR for specifying the location services (SRV)) http://www.ietf.org/rfc/rfc2052.txt?number=2052 — RFC 2246 (TLS Protocol Version 1.0) http://www.ietf.org/rfc/rfc2246.txt?number=2246 — RFC 2327 (SDP: Session Description Protocol) http://www.ietf.
— RFC 3263 (Session Initiation Protocol (SIP): Locating SIP Servers) http://www.ietf.org/rfc/rfc3263.txt?number=3263 — RFC 3264 (An Offer/Answer Model with the Session Description Protocol (SDP)) http://www.ietf.org/rfc/rfc3264.txt?number=3264 — RFC 3265 (Session Initiation Protocol (SIP) - Specific Event Notification) http://www.ietf.org/rfc/rfc3265.txt?number=3265 — RFC 3311 (The Session Initiation Protocol (SIP) UPDATE Method) http://www.ietf.org/rfc/rfc3311.
HP Encourages Your Comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to: feedback@fc.hp.com Include the document title, manufacturing part number, and any comment, error found, or suggestion for improvement you have concerning this document.
1 Introduction With the increase in the mobility of people and the number of mobile devices that they use, it is important to stay connected irrespective of the geographical location of a person and the mobile device used. The Session Initiation Protocol (SIP) provides converged communication between various mobile devices and enables seamless data and voice transfer.
SIP supports the following while establishing and terminating sessions between user agents: • • • • • Determines the end system to be used for communication. Determines the willingness of the called user to participate in a call. Determines the media and media parameters to be used for a particular session. Establishes session parameters at both the ends of a session. Manages a session by including transfer and termination of sessions, modifying session parameters, and invoking services.
A user agent can function in the following roles: • User Agent Client A user agent client (UAC) is a client application that initiates a new SIP request. The application acts as a UAC only for the duration of the transaction when it sends a SIP request. If the application receives a request, UAC assumes the role of a user agent server for processing that transaction. The requests issued by a UAC are INIVITE, ACK, OPTIONS, BYE, CANCEL, and REGISTER.
the redirect server does not initiate its own SIP request. Instead, it redirects the request back to the client indicating that the client must attempt a different route to reach the recipient. This method of identifying a client irrespective of its location enables a client to move geographically and still remain contactable with the same SIP identity. Unlike a user agent server, the redirect server does not accept or terminate calls.
Figure 1-1 SIP Protocol Structure Figure 1-1 discusses the following layers: • • The application layer provides application programs with an interface to communicate and transfer data across the network. Following are the SIP protocol layers: — A transaction user (TU) can be any SIP entity except a stateless proxy. A transaction user uses transactions to send a request to the peer.
• • The network transport layer is the transport layer in the IP stack. It enables transfer of data between end points by using the services of the network layer. This layer has two primary protocols, TCP and UDP. The TCP supports reliable and sequential packet delivery through error recovery and flow control mechanisms. The UDP is a simple message-based connectionless protocol compared to TCP.
Call-ID: 132059753@local.hp.com Content-Type: application/sdp CSeq: 1 INVITE Contact: Content-Length: 187 v=0 o=user1 51633745 1348648134 IN IP4 16.188.155.140 s=Interactive Conference c=IN IP4 224.2.4.4/127 t=0 0 m=audio 3456 RTP/AVP 0 22 a=rtpmap:22 application/g723.1 The following are the different parts of a request: First Line Via From To Subject Call ID Content-Type Command sequence (CSeq) Contact Content-Length Contains the method name, such as INVITE.
ACK BYE CANCEL INVITE OPTIONS REGISTER Confirms that the client has received a final response to an INVITE request. Indicates to the server that the client wants to release the call. Cancels a pending user agent client request. Indicates that the user or service is being invited to participate in a session. Queries a server with regard to its capabilities. Registers contact information with a SIP server.
SIP/2.0 200 OK Via: SIP/2.0/UDP local.hp.com;received=16.1.55.40 From: To: TPU Call-ID: 132059753@local.hp.com Content-Type: application/sdp CSeq: 1 INVITE Contact: Content-Length: 187 v=0 o=user1 51633745 1348648134 IN IP4 16.188.155.20 s=Interactive Conference c=IN IP4 224.2.4.4/127 t=0 0 m=audio 3456 RTP/AVP 0 22 a=rtpmap:22 application/g723.
Table 1-2 Specific Response Types Description Response Code 1xx (Provisional) Specific-Response Type Code TRYING 100 RINGING 180 CALL_IS_BEING_FORWARDED 181 QUEUED 182 SESSION_PROGRESS 183 OK 200 ACCEPTED 202 MULTIPLE_CHOICES 300 MOVED_PERMANENTLY 301 MOVED_TEMPORARILY 302 USE_PROXY 305 ALTERNATIVE_SERVICE 380 2xx (Success) 3xx (Redirection) 26 Introduction
Table 1-2 Specific Response Types (continued) Description Response Code 4xx (Client error) Specific-Response Type Code BAD_REQUEST 400 UNAUTHORIZED 401 PAYMENT_REQUIRED 402 FORBIDDEN 403 NOT_FOUND 404 METHOD_NOT_ALLOWED 405 NOT_ACCEPTABLE 406 PROXY_AUTHENTICATION_REQUIRED 407 REQUEST_TIMEOUT 408 GONE 410 REQUEST_ENTITY_TOO_LARGE 413 REQUEST_URI_TOO_LONG 414 UNSUPPORTED_MEDIA_TYPE 415 UNSUPPORTED_URI_SCHEME 416 BAD_EXTENSION 420 EXTENSION_REQUIRED 421 INTERVAL_TOO_BRIEF 4
Table 1-2 Specific Response Types (continued) Description Response Code 5xx (Server error) Specific-Response Type Code REQUEST_PENDING 491 UNDECIPHERABLE 493 SERVER_INTERNAL_ERROR 500 NOT_IMPLEMENTED 501 BAD_GATEWAY 502 SERVICE_UNAVAILABLE 503 SERVER_TIMEOUT 504 VERSION_NOT_SUPPORTED 505 MESSAGE_TOO_LARGE 513 BUSY_EVERYWHERE 600 DECLINE 603 DOES_NOT_EXIST_ANYWHERE 604 SESSION_NOT_ACCEPTABLE 606 6xx (Global error) Message Parts Following are the parts of a SIP message: • • • S
Table 1-3 Message Parts SIP Message Name Description Start Line Denotes the beginning of a SIP message. A start line can be either a request or a response. A request start line contains a method name, the SIP URI to which the message is sent, and the SIP version number. The response start line contains the SIP version number, the status code, and the description for the response phrase. Following are sample SIP start lines: • Request start line INVITE sip:tpu@hp.com SIP/2.0 • Response start line SIP/2.
Figure 1-2 illustrates the interaction between user agents while a session is being established and terminated. Figure 1-2 Establishing and Terminating a Call The following steps describe the sequence of messages exchanged between the user agents: • The following messages are exchanged while establishing a session: 1. UA1 sends an INVITE request message to invite UA2 to participate in the session. 2. UA2 responds with a 100 - Trying response message to indicate that the request has been received. 3.
Figure 1-3 Call Setup Using a Proxy server The following messages are exchanged while UA1 uses a proxy server to connect to UA2: 1. 2. 3. 4. 5. 6. 7. 8. 9. UA1 sends an INVITE request to UA2. This request is first sent to the proxy server and then to UA2. The proxy server responds with a 100–Trying message to UA1. The proxy server looks up user2's current location in a location service. The location service returns user2's current location.
10. The proxy server forwards the 200–OK response back to UA1. 11. UA1 sends an ACK directly to UA2. Using the Redirect Server This section discusses the steps involved in establishing a call that uses a redirect server. Figure 1-4 illustrates the interaction between the user agents, redirect server, and the location service while establishing a call. Figure 1-4 Call Setup Using a Redirect Server The following steps describe how a call is established using a redirect server: 1. 2. 3. 4. 5. 6. 7.
Implementations of SIP on HP-UX The HP implementation of SIP is available on the following stacks: • • C SIP Java SIP The following sections discuss the documentation available for these stacks. This section addresses the following topics: • • “Documentation for the C SIP Stack” “Documentation for the Java SIP Stack” (page 33) Documentation for the C SIP Stack HP uses the C SIP stack from RADVISION Ltd. to support SIP on the C stack in the HP-UX operating system.
2 JSR32 JAIN SIP APIs This chapter discusses the JSR32 stack architecture, the main objects in the stack, the packages and factories available in the stack, and the JSR32 features. This chapter addresses the following topics: • • • “Overview” “JSR32 Architecture” (page 36) “HP-UX JSR32 Features” (page 42) Overview The SIP protocol, as defined in RFC 3261 (Session Initiation Protocol), is accepted as the industry standard for establishing sessions between users in a network.
• • • • Invoke appropriate application handlers for message arrivals and protocol-specific events, such as transaction timeouts. Provide transaction support, and manage transaction state and lifetime on behalf of a user application. Provide dialog support, and manage dialog state and lifetime on behalf of a user application. Handle retransmissions that reduces complexity for applications acting as user agents.
This section addresses the following topics: • • • • “JSR32 SIP Stack” (page 37) “JSR32 Packages” (page 39) “JSR32 Objects” (page 39) “JSR32 Factories” (page 41) JSR32 SIP Stack This section discusses the different layers in the JSR32 SIP stack. Figure 2-1 (page 37) illustrates the different layers and the interaction between them in the JSR32 SIP architecture.
The JSR32 SIP architecture includes the following components: • SipListener This interface represents the application view to a SIP stack and defines the application's communication channel to the SIP stack. It also defines the methods required by an application to receive and process events that are generated by an object implementing the SipProvider interface.
Encoder • Initiation Protocol), and converts to a format that an application can interpret and process. Specifies an interface that encodes the message from the application and sends them over the network as raw bytes. Network Contains raw bytes that is sent to the JSR32 SIP stack for further processing. JSR32 Packages HP provides the following packages for the Java SIP stack: • General Package (javax.
An application can have multiple SipStack objects. However, only a single SipStack can be associated with an IP address. The SipStack object defines the following methods to control the architecture and setup of the SIP stack: • • Creation or deletion of SipProviders. A SipProvider represents messaging objects that can be used by an application to send request and response messages statelessly or statefully using client and server transactions. Creating or deletion of ListeningPoints.
Remote Target secure Route Set Specifies the address from the contact header field of the request or response, or refresh request or response. Determines whether the dialog is secure. Specifies an ordered list of URIs. Transaction Object The transaction object represents a generic transaction interface that defines the methods that are common to client and server transactions. Transaction is a fundamental component of SIP.
• HeaderFactory This interface defines methods to create new headers objects. • MessageFactory This interface defines methods to create new request and response objects. HP-UX JSR32 Features This section discusses the features in the HP implementation of the JSR32 APIs. This section addresses the following topics: • • • • • • • • • • • “Event Notification” (page 42) “The REFER Method” (page 43) “SIP for Telephones” (page 43) “Provisional Response Acknowledgement in SIP” (page 43) “E.
The REFER Method The SIP stack enables the implementation of transfer services using the REFER method, as defined in RFC 3515 (The Session Initiation Protocol (SIP) Refer Method). The REFER method can be used in call transfer applications. It indicates that the recipient must contact a resource using the contact information provided in the request. The protocol for emitting and responding to a REFER request is identical to that of a BYE request.
E.164 Number Mapping In voice over IP (VoIP) networks, an endpoint is identified by an IP address and a telephone number. When a user calls a SIP remote end point from a PSTN network, only the telephone number is known. The SIP uniform resource identifiers (URI) is unknown. Therefore, it is important to translate the telephone number into the SIP URI for the call to be established.
Persistent Connection The SIP stack uses a single TCP or TLS connection for different messages, transactions, or dialogs. However, the frequent opening and closing of TCP connections is not desirable, because of the extra messaging overhead in TCP and TLS connections. Hence, SIP supports connection persistency, which is the reuse of an open connection. The SIP stack enables connection reuse by specifying that a message can be sent on an existing open connection.
Table 2-1 SIP Stack Parameters (continued) 46 Parameter Name Description javax.sip.EXTENSION_METHODS Informs the underlying implementation about supported extension methods that create new dialogs. This configuration flag must be used for dialog creating extension methods; other extension methods that do not create dialogs can be used using the method parameter on request, assuming that the implementation understands the method.
Table 2-1 SIP Stack Parameters (continued) Parameter Name Description com.hp.net.javax.sip.SERVER_LOG Logs valid incoming messages. If SERVER_LOG is not specified (that is, it contains a null value) and the value of TRACE_LEVEL is more than 16, the error message are printed to standard output. com.hp.net.javax.sip.DEBUG_LOG Specifies the location for storing the debug log messages. com.hp.net.javax.sip.TRACE_LEVEL Sets tracing and debugging using the TRACE and DEBUG strings.
Table 2-1 SIP Stack Parameters (continued) Parameter Name Description com.hp.net.javax.sip.CACHE_CLIENT_CONNECTIONS Specifies a boolean value that closes the server socket after a client transaction enters the TERMINATED state, if CACHE_CLIENT_CONNECTIONS is set to false. This enables a client to release buffer threads and socket connections that are associated with a client transaction after the transaction terminates, at the expense of the performance of the stack. The default value is true. com.hp.net.
Table 2-1 SIP Stack Parameters (continued) Parameter Name Description com.hp.net.javax.sip.PASS_INIVTE_NON2XX_ If this parameter is set to true, the listener views the ACK for the non-2xx responses. The default value is false. ACK_TO_LISTENER com.hp.net.javax.sip.MAX_LISTENER_ RESPONSE_TIME Specifies the maximum time (in seconds) before sending a response to a server transaction. The stack deletes this transaction if a server does not send a response within this period of time.
Table 2-1 SIP Stack Parameters (continued) Parameter Name Description com.hp.net.javax.sip.LOG_FACTORY Specifies the fully qualified classpath for an implementation of the MessageLogFactory. The SIP stack calls the MessageLogFactory functions to log the messages that are received or sent. The MessageLogFactory enables you to log auxiliary information related to the application or environmental conditions into the log stream. com.hp.net.javax.sip.
3 Creating an Application This chapter describes how to create an application. Creating an application involves the following tasks: 1. 2. 3. 4. 5. 6. Creating an instance of the SIP stack Creating instances of factory implementations Creating an instance of the SipProvider Forming a SIP message Sending a SIP message Processing an event The subsequent sections in this chapter describe these tasks in detail.
Example 3-1 Setting the TRACE_LEVEL Stack Parameter To set the TRACE_LEVEL stack parameter, set the property as follows: prop.setProperty(“com.hp.net.javax.sip.TRACE.LEVEL”, “32”); 4. Configure the SIP stack using the following method: sipStack sipStack=sipFactory.createSipStack(prop); Creating Instances of Factory Implementations You must create instances of the factory implementations before you can create a SIP message.
Forming a SIP Message You can use factories to create a SIP message. Therefore, you must create the factories before forming a SIP message. Follow this procedure to create factories: 1. To create an address, use the AddressFactory interface, as follows: Address address=addressFactory.createAddress(URI); Address address=addressFactory.createAddress(String); Address address=addressFactory.createAddress(String, URI); 2.
To use an existing client or server transaction formed by the arrival of request or response events, use the following methods: — ServerTransaction str=RequestEvent.getServerTransaction(); — ClientTransaction ctr=ResponseEvent.getClientTransaction(); 2. Send the request or response using the obtained transaction object, specified as follows: ctr.sendRequest(); str.sendResponse(Response); • Follow this procedure to send a message in a dialog-stateful scenario: 1.
4 Compiling and Running Applications Using the HP-UX JSR32 Kit This chapter describes how to compile and run applications that use the JSR32 APIs. Follow this procedure to compile and run applications that use JSR32 APIs: 1. Set the PATH variable to the specific Java Development Kit (JDK) version, as specified in the following example: export PATH=$PATH:/opt/java1.5/bin 2. Set the class path to the location of the following jar files: • JainSipApi1.2.jar • JainSipRi1.2.jar • concurrent.jar • log4j-1.2.8.
5 Troubleshooting HP JSR32 APIs This chapter discusses the exceptions raised by the JSR32 APIs. Table 5-1 lists the exceptions raised by the JSR32 APIs and their causes. Table 5-1 JSR32 API Exceptions Exception Name Cause The javax.sip Exceptions InvalidArgumentException An application passes an invalid argument, such as an invalid numerical value. ObjectInUseException A method is unable to delete a specified object, because the object is still in use by the underlying implementation.
Glossary Dialog A dialog is a peer to peer association between communicating SIP end points. Java Community Process Java Community Process (JCP) is the home of the international developer community whose chartert is to develop and evolve Java technology specifications, reference implementations, and technology compatibility kits.
Index ACK method, 24 AddressFactory, 41 application layer, 21 sample, 29 header field, 29 HeaderFactory, 42 HTTP (see HyperText Transfer Protocol) HyperText Transfer Protocol, 17 B I A BYE method, 24 C C SIP stack, 33 call ID, 40 CANCEL method, 24 client error response code, 27 command sequence, 23 compiling an application, 55 example, 55 configure stack parameter, 51 configuring SIP stack, 52 creating factory, 53 header, 53 listening point, 52 request message, 53 response message, 53 SipProvider, 52
MessageFactory, 42 N network layer, 22 network transport layer, 22 NOTIFY method, 24 O OPTIONS method, 24 P parser, 38 parsing SIP message, 54 PRACK method, 24 PRACK response, 43 presence service, 19 provisional response code, 26 proxy server presence service, 19 stateful, 19 stateless, 19 PSTN (see public switched telephone network) public switched telephone network, 42, 43 Q QoS (see quality of service) quality of service, 43 R RAck field, 43 Real-Time Streaming Protocol, 17 Real-Time Transport Proto
sample, 24 status code, 24 SIP-T (see SIP for telephones) SipFactory, 41, 51 SipListener, 38 SipProvider, 38, 52 creating, 52 example, 52 SIPS (see secure SIPS) SipStack object, 40 start line, 29 sample line, 29 stateful proxy server, 19 stateless proxy server, 19 stateless scenario, 53 status code, 24 status line detail, 25 stream control transmission protocol, 21 SUBSCRIBE method, 24 success response code, 26 V voice over IP, 44 VoIP (see voice over IP) T TCP (see transmission control layer) TimeoutEven
