JAIN(tm) SIP Release 0.7 Specification Standard Java(tm) Interface to the Session Initiation Protocol (SIP)

Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

The JAIN SIP API The JAIN SIP Application Programming Interface (API) is part of the JAIN SIP 0.7 Specification. A description of the classes, interfaces and methods that comprise the API as well as an example of how to implement from the API can be found in the JAIN SIP API Javadoc.

The JAIN SIP API Requirements Specification The Requirements Specification provides a high level overview of JAIN and the JAIN SIP API Specification as well as explaining the JAIN Architectureand the functionality provided by each of the requirements defined within the document.

The JAIN SIP Reference Implementation (RI) Specification The JAIN SIP Reference Implementation (RI) is a an example Java program that emulates the functions of a SIP stack in order to verify that JAIN SIP applications are compatible with the JAIN SIP specification. The RI can therefore be used to help develop and debug a JAIN SIP application in the absence of an JAIN SIP Compliant SIP Stack. The purpose of the the RI Specification is to outline the requirements for setting up the RI and to list the scope, limitations and restrictions of the RI.

The JAIN SIP Technology Compatability Kit (TCK) Specification The purpose of the JAIN SIP TCK is to verify that a JAIN SIP implementation is compatible with the JAIN SIP API Specification. The TCK Specification details the test cases which an implementation of JAIN interfaces must pass in order to be considered compliant with the JAIN SIP Specification.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

JAIN(tm) SIP API Requirements Specification Version 0.7

Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE

IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Table Of Contents Chapter 1: Objectives and Scope ❍

1.1 JAIN SIP API Specification

Chapter 2: Introduction ❍

2.1 System Overview

Chapter 3: Requirements Definition ❍

3.1 The JAIN SIP Object Model

❍

3.2 JAIN SIP Naming Convention

❍

3.3 JAIN SIP Architecture

❍

3.4 Generic Primitives

4 External Requirements ❍

4.1 External Interfaces

❍

4.2 Resource Requirements

❍

4.3 Acceptance Test Issues

❍

4.4 Documentation Requirements

❍

4.5 Portability Requirements

❍

4.6 Quality Requirements

❍

4.7 Maintainability Issues

❍

4.8 Compatibility Requirements

❍

4.9 Specification Deliverables

❍

4.10 Constraints, Assumptions and Dependencies

5 APPENDIX I - References 6 APPENDIX II - Abbreviations and Definitions ❍

6.1 Abbreviations

❍

6.2 Terms

7 APPENDIX III - Figures and Tables 8 APPENDIX IV - SIP Expert Group Members 9 APPENDIX V - Document Information Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

1 Objectives and Scope Java™ API's for the Integrated Network (JAIN™) Framework brings Service Portability and Network Convergence into the Telephony Network. JAIN encompasses a standard set of interfaces for service creation and a number of standard interfaces for service execution. The service creation interfaces allow new services to be described as JavaBeans™ [3], which can be connected using standard graphics tools to create new services. The service execution environment includes Java interfaces to a number of telephony protocols, such as the Signaling System No. 7 ISDN User Part (ISUP) and the Media Gateway Control Protocol (MGCP). How the development of JAIN SIP fits into overall JAIN program management is specified in Figure 1: JAIN Consortium Layout.

Figure 1: JAIN Consortium Layout The reason we need JAIN is the technological roadblock presented by interfaces to switches, computers, and services. The problem, which is deep inside the network, is that services cannot be transported from one system to another. The JAIN specification defines an interface into the specific domain of each vendor’s SS7 stack and IP protocols, and provides a programming interface (API) to any vendor’s stack for use by application developers. The need to define a standard API specification has become paramount as users of the telephone and the Internet demand better, coherent services. Java provides a perfect environment for developing such a standard. The Java “write once, run anywhere” philosophy promotes interoperability between JAIN SIP stack providers, enabling Network Equipment Providers and Call Processing Software Providers to choose between JAIN SIP vendors and to provide services compatible with any system. A Java approach to telephony offers telephone service providers interoperability between hardware and software network elements. As a consequence, Network Equipment Providers

and Call Processing Software Providers will be able to bring their true value to the market unimpeded by issues of incompatibility and lack of interoperability. The scope of JAIN SIP is to define a Java Application Programming Interface (API) for the Session Initiation Protocol [2]. The scope of the API does not extend to call control; this must be provided by a higher level API e.g. JCC. This document is laid out in the following format: ● Chapter 1 Objectives and Scope: This chapter provides an insight to JAIN, why we need JAIN, and what needs to be achieved in order to provide JAIN SIP. ● Chapter 2 Introduction: This chapter provides an introduction to the Session Initiation Protocol, how it operates, and how its operation can be mapped logically to the real world. ● Chapter 3 Requirements Definition: This chapter defines the requirements necessary to develop version 1.0 of the JAIN SIP API. Each requirement is stated succinctly, followed by an explanatory statement that provides any additional information that may be needed for full understanding of the requirement. ● Chapter 4 External Requirements: This chapter outlines the requirements that don’t directly affect an implementation of the JAIN SIP API, but that may affect the development of the API. ● Chapter 5 Appendix I: This chapter lists the reference materials that are cited throughout this document. ● Chapter 6 Appendix II: This chapter lists the abbreviations used throughout the document, as well as any terms that may need additional explanation. ● Chapter 7 Appendix III: This chapter lists the figures and tables that appear in this document. ● Chapter 8 Appendix IV: This chapter provides a brief summary of the partner companies involved in the development of version 1.0 of the JAIN SIP API. ● Chapter 9 Appendix V: This chapter outlines the control, distribution, and history of this document. ● Chapter 10 Change Log: This chapter is used to document any changes that may be incorporated into this document after it has been approved.

1.1

JAIN SIP API Specification

The JAIN SIP API specification is to provide a standard portable interface for the transfer of information between SIP Clients and SIP Servers, which enable applications for converged networks by providing call control elements. The purpose of this document is to define the

requirements on for the JAIN SIP API specification. This document contains a concise list of all the requirements that need to be satisfied for public release of the JAIN SIP API specification. It is important to note the syntax of the requirements, in that: ● If the wording of a specific requirement includes ‘shall’ then the incorporation of this requirement in the JAIN SIP API specification is mandatory. ● If the wording of a specific requirement includes ‘should’ then the incorporation of this requirement in the JAIN SIP API specification is strongly recommended, but is not mandatory. The deliverables of the JAIN SIP API specification will encompass: ● A Java API specification, which will define a common interface for accessing the functionality of proprietary implementations of the SIP. ● The Reference Implementation (RI) is the "proof of concept" implementation of the Specification. The RI will emulate or simulate the functions of a SIP stack in order to verify the requirements in this specification. The intention of the RI is not to implement a SIP stack or to replace vendor SIP stacks. The purpose of the RI is to provide a means for demonstrating that a Java application written to the JAIN SIP API specification is compatible with that specification. ● The Technology Compatibility Kit (TCK) tests the implementation of JAIN interfaces for compliance to the JAIN SIP Specification. The purpose of the JAIN TCK is to verify that a Java SIP protocol implementation is compatible to the JAIN SIP API Specification. The RI and the TCK do not have to be delivered until the public release of the JAIN SIP API specification. The Participant who’s Expert is chosen, as Specification Lead is typically responsible for obtaining the appropriate rights to the TCK and the RI to fulfill the Java Specification Participant Agreement (JSPA). The JAIN SIP API specification will follow the Java language naming convention and strictly follow the functionality of the SIP specifications used. The Java specification definition and process can be found at http://java.sun.com/aboutJava/communityprocess/

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

2 Introduction The purpose of the Session Initiation Protocol is described below.The text has been taken directly from the abstract of the SIP Specification, RFC 2543 [2]: The Session Initiation Protocol (SIP) is an application-layer control (signaling) protocol for creating, modifying and terminating sessions with one or more participants. These sessions include Internet multimedia conferences, Internet telephone calls and multimedia distribution. Members in a session can communicate via multicast or via a mesh of unicast relations, or a combination of these. SIP invitations used to create sessions carry session descriptions, which allow participants to agree on a set of compatible media types.SIP supports user mobility by proxying and redirecting requests to the user's current location. Users can register their current location. SIP is not tied to any particular conference control protocol. SIP is designed to be independent of the lower-layer transport protocol and can be extended with additional capabilities. SIP client is an application program that sends SIP requests. SIP server is an application program that accepts SIP requests. In order to service requests SIP server sends back SIP responses for those requests. SIP is a peer-to-peer protocol, as opposed to a master-slave protocol. A SIP client could be a server in another transaction. SIP allows a client to send messages to any SIP-enabled server without being aware of the type of server that it is communicating with. The behavior of SIP client is based on the responses without considering where the responses came from. The different types of SIP servers include User Agent, Proxy, Redirect and Registrar. The objective of the JAIN SIP API specification is to specify a Java API that will provide the interfaces and classes required for an application to instantiate objects. These objects expose and implement the JAIN SIP API that allows the application to interact through the API with the SIP stack encapsulated by these objects. An architecture that depicts the role of SIP relative to that of other packet-based protocols (e.g. MGCP, etc.) is shown in Figure 2: Converged Network Architecture.

Figure 2: Converged Network Architecture Note: Not all of the possible types of SIP endpoints have been shown. Only control protocols have been shown; media streams between edge devices have been omitted for sake of clarity.

2.1

System Overview

SIP endpoints are devices that contain SIP User Agents. These devices are considered intelligent endpoints. There are many places in the converged network that SIP User Agents will reside. Examples of endpoints that contain SIP User Agents are:

Softswitches (SS) or Media The devices that control the different types of Gateway Controllers (MGC) Media Gateways (MG) listed below.

Media Gateways (MG)

Etherphones PC based phones End-user devices Intelligent screen phones

There are many types of gateways that can be directly SIP enabled, however it is likely that the SIP User Agent will reside on the MGC. MGs include: ● Trunking gateways ● Voice-over-ATM gateways ● Residential gateways ● Access gateways ● Business gateways Hardware IP phone. Software IP phone that runs on a PC client. Hand-held IP phone devices. Smart SIP endpoints with graphics displays.

An example of a SIP call setup and tear down between a User Agent Client (caller) and a User Agent Server (callee), traversing a SIP Proxy Server is show below in Figure 3: Simple SIP Call Setup and Tear Down, Via a SIP Proxy Server.

Figure 3: Simple SIP Call Setup and Tear Down, Via a SIP Proxy Server

In the Figure above, steps 1-9 represent call setup and steps 10-11 represent call tear down. The following table explains, in detail, the messages, which are passes between the User Agent Client and User Agent Server.

1 INVITE

The User Agent Client initiates a call with the User Agent Server, via the Proxy Server by sending an INVITE message to the Proxy Server that is destine for the User Agent Server. 2 100/TRYING The Proxy Server responds immediately with a 100 response to confirm that it has received the message. 3 INVITE The Proxy Server forwards the INVITE message to the User Agent Server, now that it has located that user. 4 100/TRYING The User Agent Server responds immediately with a 100 response to confirm that it has received the message. 5 180/RINGING After processing the INVITE, and notifying the end user that a call has arrived, the User Agent Server responds with a 180 response to indicate that the terminating side it ringing. 6 180/RINGING The Proxy Server forwards the 180 response to the User Agent Client that originated the INVITE request. 7 200/OK After the user accepts the connection, the User Agent Server sends a 200 response to the Proxy Server, indicating that the call has been accepted. 8 200/OK The Proxy Server forwards the 200 response to the User Agent Client that originated the INVITE request. 9 ACK The User Agent Client acknowledges that receipt of the final response to the INVITE message by sending an ACK. (media stream) After the ACK, the media stream is set up and the session is in progress. 10 BYE When either side wants to end the session, it sends a BYE request to the other side. This, as with the ACK, typically will not traverse the Proxy Server (unless the Proxy Server specifically requests this, as is the case with a Firewall Proxy Server) since the network path is already established. 11 200/OK The User Agent Client sends a 200 response to the User Agent Server that originated the INVITE request.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

3 Requirements Definition 3.1

The JAIN SIP Object Model

A JAIN SIP object, or, rather, the class from which it is instantiated, can be expressed as either a traditional Java program or as a JavaBean [3], where a JavaBean [3] is a reusable software component/object. An application (e.g., a Media Gateway Controller) that needs to make use of the services of a SIP stack that is encapsulated as a JAIN SIP object can also be expressed in either of these ways, as well. JAIN is built upon standardized Java APIs and Object technology. In Object Technology, data and programming logic are treated as objects. Unlike traditional computer programs, objects can be readily integrated into a running environment, accessed and managed remotely, and debugged and maintained in live systems by standardized interfaces, etc. While JAIN does not mandate that all applications must be built as JavaBeans [3], the design of the API specification will not preclude any application from executing as a JavaBean [3]. The unifying features of a JavaBean [3] are explained with examples at http://java.sun.com/beans/docs/index.html. The main points are: ❍

❍

❍

❍

Introspection: Can be used by an application builder tool to discover the properties, methods and events of a JAIN SIP object. Customization: Allows an operator to dynamically change the properties of a JAIN SIP object at run time using an application builder tool. Events: Can be used as the vehicle for bi-directional communication between an application and a JAIN SIP object, so that the invocation of a SIP method can be accomplished by the passing of an event object between the application and the JAIN SIP object that will perform the method. Persistence: Allows the state of a JAIN SIP object to be stored for retrieval at a later time.

The three most important features of a JavaBeans [3] are: ❍

❍

❍

Property Management: Properties are named attributes associated with a bean that can be read or written by calling appropriate methods on the bean. Method Management: A JavaBean [3] exports both standard and extended Java methods, which can be called from other objects or from a scripting environment, such as HTML invoking an applet. By default, all of the bean's public methods will be exported. State Management: Events provide a way for one object to notify other objects that a change in state has occurred. Under the Java event model, an event listener object can be registered with an event source. When the event source detects a state change, it will call the appropriate method on the event listener object.

REQ-OM-01-01: The API specification shall adhere to the JavaBeans Model. If the JAIN SIP API specification is implemented using JavaBeans [3], it offers the advantage of using reusable objects in a plug and play fashion.

REQ-OM-02-01: The API specification shall not restrict an implementation of the API to JavaBeans. This permits the JAIN SIP API specification to be implemented in standard Java code.

3.2

JAIN SIP Naming Convention

JAIN SIP objects must conform to a specific naming convention in order to support JavaBean [3] implementation. For a JavaBean [3] to expose a property, i.e. within a visual tool, it must supply an access method "get" to read the property value and/or a "set" method to write the property value. These "get" and "set" methods have the following signatures:public get();public void set( a); If we discover a matching pair of get and set methods that take and return the same type, then we regard these methods as defining a read-write property whose name will be . For a Boolean property the access method "get" signature changes to: public boolean is();

REQ-NC-01-01: The API specification shall follow the JavaBean naming convention.

REQ-NC-02-01: All access methods shall throw an exception when accessing a parameter that has not previously been set or is not supported by a specific implementation. Adherence to this requirement will provide an efficient technique for determining whether a parameter has been set or is not supported by an implementation, and for initiating a corrective action. Adherence is also consistent with Java language programming style.

3.3

JAIN SIP Architecture

For simplicity, the illustration below, Figure 4: JAIN SIP Architecture, represents a generic SIP Client and a generic SIP Server.

Figure 4: JAIN SIP Architecture

The TCK and the RI will test the JAIN SIP API specification, where the TCK is equivalent to the application/SIP Listener and the RI is equivalent to the SIP stack/SIP Provider. It is important to note that the RI is not an emulation of a SIP/IP stack. ❍

❍

❍

JAIN SIP Events: Within the API, SIP messages are encapsulated as Message objects that are passed between the JAIN SIP Provider and the JAIN SIP Listener. JAIN SIP Provider: Within the API, the JAIN SIP Provider is defined as the entity that provides an application access to the services of the SIP stack. JAIN SIP Listener: Within the API, the JAIN SIP Listener is defined as the entity that uses the services provided by the JAIN SIP Provider.

Thus, the JAIN SIP API must provide definitions for the Listener and Provider interfaces, for the Message interfaces that correspond to SIP messages, and for the means for Listeners to register with corresponding Providers in order to send and receive these primitives.

3.3.1 3.3.1.1

Event Requirements JAIN SIP Event Processing

REQ-ER-01-01: The API specification shall provide the functionality that will enable SIP messages and their associated parameters to be sent between the JAIN SIP Provider and the JAIN SIP Listener as Events. JAIN SIP messages are passed between the protocol stack to the application as Event Objects. Event handling methods defined in the EventListener interface conform to a standard naming convention: void ( event); where the is a subclass of java.util.EventObject. Event Provider classes provide methods for registering and de-registering event listeners, which allow potential EventListeners to establish an event flow from that Provider to the Listener. The standard naming convention for EventListener registration is: public void add ( listener) throws java.util.TooManyListenerException, java.util.ListenerAlreadyRegisteredException The current architecture of SIP makes it unlikely that more than one Listener would act on a single SIP Event Object, so in that case the API implementation should preclude more than one Listener from registering on a given Provider. (An implementation may permit multiple Listeners for high availability or load-sharing, but this is not specifically addressed by the API). Note that no requirement is placed on the Listener to catch the exception that may be thrown. However the ListenerAlreadyRegisteredException should always be thrown if the same JAIN SIP Listener, tries to re-register with the JAIN SIP Provider. public void remove( listener) throws java.util.ListenerNotRegisteredException; The ListenerNotRegisteredException should always be thrown if this method is invoked on a specific JAIN SIP Listener, which is not registered with that JAIN SIP Provider. An overview of the JAIN SIP Event Processing model is illustrated in Figure 5: JavaBean™ Event Model.

Figure 5: JavaBean™ Event Model

Invoking the add method adds the given listener to the set of Event Listeners registered for events associated with the . Similarly invoking the remove method removes the given Listener from the set of Event Listeners registered for Events associated with the . The error handling of the possible exceptions are all specific to the implementation of the JAIN SIP specification, for example: ❍ ❍ ❍ ❍

Adding the same JAIN SIP Listener more than once to the same JAIN SIP Provider. Removing a JAIN SIP Listener more than once from the same JAIN SIP Provider. Removing a JAIN SIP Listener that is not registered with a JAIN SIP Provider. Adding more JAIN SIP Listeners than a JAIN SIP Provider can handle.

3.3.1.2

JAIN SIP Events

JAIN SIP Events, which are encapsulated SIP messages, contain both input parameters provided to the Listener by the Provider and output parameters returned by the Listener to the Provider.

REQ-ER-02-01: The API specification shall define a method which accepts a generic Event Object corresponding to all SIP primitives, from the invoking entity (the Provider), to the registered Listener method that processes that primitive.

REQ-ER-03-01: The API implementation shall provide methods defined on each Event Object for accessing both input and output parameters encapsulated within the Event Object. This will provide SIP message passing from object to object, by following the JavaBeans event model. [3]

3.3.2

JAIN SIP Provider Requirements

The implementation of the JAIN SIP Provider interface provides a vendor-specific SIP stack with the ability to communicate with a JAIN SIP Listener implemented in an application (e.g., a User Agent or Proxy Server).

REQ-PR-01-01: At most one JAIN SIP Provider shall be bound to a given SIP port at any time. Since permitting more than one JAIN SIP Provider on a given SIP port would not be useful.

REQ-PR-02-01: The JAIN SIP Provider shall pass an Event to at most one registered JAIN SIP Listener. Since at most one Listener shall be registered with a given Provider (usually), violation of this requirement would signify a serious implementation error. (As mentioned above, an implementation may permit multiple Listeners for the purposes of high availability or load-sharing, but a JAIN SIP application must ensure only one Listener actually handles an event)

3.3.2.1

JAIN Factory Requirements

Within Java, a Factory is a means to access vendor-specific implementations of a Java Interface or API; therefore, the JAIN IP Factory is a means to access vendor-specific implementations of the JAIN SIP Stack and Provider Interface.

REQ-PR-03-01: The API specification shall provide a common interface to access JAIN SIP Provider peers. This will ensure that additional JAIN SIP Provider peer functionality is hidden from the JAIN SIP Listener implementation, as well as providing a common method of instantiating JAIN SIP Provider objects. A common Object-Oriented design pattern used to handle this in other API's, e.g., JTAPI, is the Peer Factory.

3.3.3

JAIN SIP Listener Requirements

REQ-LR-01-01: A JAIN SIP Listener shall be able to register with any JAIN SIP Provider. This ensures that all JAIN SIP Listeners are portable over all JAIN SIP Providers, which is a fundamental requirement of the Java programming language i.e. “write-once, run-anywhere.”

3.3.3.2

JAIN SIP Listener Registration

REQ-LR-03-01: A JAIN SIP Listener shall register with a JAIN SIP Provider to receive SIP messages from that Provider by using the addListener method defined by that Provider.

3.4

Generic Primitives

A generic set of primitives shall be created that abstracts the functionality of the primitives to support extensions.

REQ-GP-01-01: The API shall incorporate a common set of primitives that will map to protocol extension information. This provides a higher level of abstraction within the API.

REQ-GP-02-01: The API shall treat all primitives that are not common to the base protocol as optional.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

4 External Requirements 4.1

External Interfaces

REQ-EI-01-01: The API specification shall be compatible with the Java Platform v1.2.2 Core API Specification or later. The added features of the new Java Platform v1.2.2 can be viewed at http://java.sun.com/products/jdk/1.2/

4.2

Resource Requirements

REQ-RR-01-01: In order to execute the JAIN SIP Technology Compatibilty Kit, or a JAIN SIP application, the following shall be required: ❍

❍

4.3

The JAIN SIP API is implemented over a JAIN compliant protocol stack or over the Reference Implementation. A Java Virtual Machine

Acceptance Test Issues

The acceptance test requirements are outlined in the Java Community Process. See http://java.sun.com/aboutJava/communityprocess/. The main Acceptance Test Requirements specified within the document include: ❍ The API specification will be acceptable to the majority of participants of the JAIN SIP expert group and the Process Management Office (Sun Microsystems). ❍ All public comments as a result of a public review shall be read, considered, documented and, if necessary, incorporated into a new review of the API specification. ❍ API deficiencies shall be documented and made available to Sun Microsystems.

4.4

Documentation Requirements

REQ-DC-01-01: The documentation shall be presented in HTML format. The documentation supporting the API needs to be supplied with and in the same format as the API (HTML).

4.5

Portability Requirements

REQ-PO-01-01: A JAIN SIP application shall be considered compliant if it can run unchanged on any JAIN SIP implementation and the JAIN SIP Reference Implementation. The main aim of the JAIN SIP process is to provide portable JAIN SIP applications that will run over any SIP stack that is JAIN-compliant.

4.6

Quality Requirements

REQ-QR-01-01: The JAIN SIP API development shall follow the Java Community Process. The Java Community Process is Sun Microsystems’s process for developing API’s. Seehttp://java.sun.com/aboutJava/communityprocess/.

4.7

Maintainability Issues

The maintainability requirements are outlined in the Java Community Process, see reference [0]. The main Maintainability Requirements within this document include: ❍ The Interpretation Guru shall be responsible for ongoing maintenance in response to requests such as clarification, interpretation, enhancements and change requests by participants and the public. ❍ A change log should be made available via a public web site that lists all revisions made to the specification by the Interpretation Guru during maintenance.

4.8

Compatibility Requirements

REQ-CR-01-01: A stack vendor’s JAIN SIP Implementation shall be compatible after passing the TCK. This will ensure that all JAIN SIP implementations can be tested to guarantee JAIN compliance. An implementation of the JAIN SIP specification will only be JAIN compliant if it passes the TCK. An acceptable standard will be set by the JAIN SIP Expert group, which will be used as a guideline with the TCK and which JAIN SIP implementations must pass in order to be compliant.

4.9

Specification Deliverables

The specification deliverables are outlined in the Java Community Process. See http://java.sun.com/aboutJava/communityprocess/. The main Specification Deliverables Requirements within this document include: ❍ ❍

❍

❍

A Java API specification shall be specified for JAIN SIP. A Reference Implementation shall be developed to uncover areas of the API that are under-defined, incomplete or ambiguous. A Technology Compatibility Kit shall be developed to ensure JAIN SIP specification compatibility. A User Guide shall be developed for the JAIN SIP specification. This will provide an overview of the JAIN SIP specification, a detailed description of the API and how its implementation can produce portable SIP applications.

4.10 Constraints, Assumptions and Dependencies This API specification will not be dependent on any other JAIN API specification, however it will be compatible with the JAIN OAM API. The JAIN OAM API may handle the provisioning and management of the JAIN SIP API depending on the vendor’s implementation of the API. The JAIN OAM specification is the interface for the service provider to provision the network. Transmissions rates, hardware characteristics, routing configurations, etc. are all covered by the JAIN OAM specification.The API specification shall provide the ability to reuse previously instantiated objects. This offers the capability of keeping object instantiation to a minimum, therefore maximizing performance.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

5 APPENDIX I [1] Sun Microsystems Open Process for Developing and Revising Java Specifications (Version 1.0, December 1998), Java Software, Sun Microsystems, Inc., http://java.sun.com/aboutJava/communityprocess/. [2] Session Initiation Protocol (SIP) IETF RFC 2543. http://www.ietf.org/rfc/rfc2543.txt [3] JavaBeans API Specification (v1.01) [4] Session Description Protocol (SDP) IETF RFC 2327. http://www.ietf.org/rfc/rfc2327.txt

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

6 APPENDIX II 6.1

Abbreviations

ANSI API CTS HTML IETF IN ITU IP JAIN JTAPI MG MGC MGCP P&M QMS RI SS SS7 SDP SIP TCP UAC UAS UDP

6.2

American National Standards Institute Application Programming Interface Compatibility Test Suite Hyper Text Mark-up Language Internet Engineering Task Force Intelligent Network International Telecommunications Union Internet Protocol Java API for Integrated Networks Java Telephony Application Programming Interface Media Gateway Media Gateway Controller Media Gateway Control Protocol Provisioning and Management Quality Management System Reference Implementation Softswitch Signaling System 7 Session Description Protocol Session Initiation Protocol Transmission Control Protocol User Agent Client Use Agent Server User Datagram Protocol

Terms

Common Interface: Interpretation Guru:

An Interface that defines a common fully functional set of methods from a specified group of protocol variants. The expert that handles the maintenance of the specification.

Listener Interface:

The Listener Interface is the Java Listener interface specified in the JAIN SIP API. Peer: A particular platform specific implementation of a Java interface or API. Provider Peer: The Provider Peer is the stack vendor specific implementation of the Provider Interface. Provider Interface: The Provider Interface is the Java Provider interface specified in the JAIN SIP API. Shall: Within the Requirements Chapter 3, if the wording of a specific requirement includes ‘shall’ then the incorporation of this requirement in the JAIN SIP specification is mandatory. Should: Within the Requirements Chapter 3, if the wording of a specific requirement includes ‘should’ then the incorporation of this requirement in the JAIN SIP specification is strongly recommended but is not mandatory. Specification Lead: The expert responsible for writing the specification with input from the other experts, and hence responsible for developing consensus within the group. This person shall possess strong diplomatic and writing skills as well as technical expertise. SIP User: Any User of the Session Initiation Protocol. User Agent Client (UAC), A user agent client is a client application that initiates the calling User Agent: SIP request. User Agent Server (UAS), called A user agent server is a server application that contacts the User Agent: user when a SIP request is received and that returns a response on behalf of the user. The response accepts, rejects or redirects the request. User Agent (UA): An application which contains both a User Agent Client and User Agent Server.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

7 APPENDIX III - Figures Figure 1: JAIN Consortium Layout Figure 2: Converged Network Architecture Figure 3: Simple SIP Call Setup and Tear Down, Via a SIP Proxy Server Figure 4: JAIN SIP Architecture Figure 5: JavaBean™ Event Model

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

8 APPENDIX IV - Edit Group

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

9 APPENDIX V - Document 9.1

Control

Document ID: Version: Location: Originator Approval Date: Status: Approver:

9.2

RQS-JAINSIP-001 0.7 dynamicsoft, Inc Chris Harris Public Review Candidate JAIN SIP Edit Group

Abstract

This document outlines the requirements specified by the JAIN SIP Edit group as a guideline for the public release of the JAIN SIP specification.

9.3

Distribution

JAIN SIP Edit Group

9.4

History

Version 0.1 0.2 0.3 0.4 0.5 0.6 0.7

Modified By Steve Mayer Mankit Lee Christopher Ross Christopher Ross Christopher Ross Chris Harris Chris harris

Date 09/27/1999 11/17/1999 01/28/2000 02/17/2000 04/21/2000 09/20/2000 11/21/2000

Description Rough Draft Updated Updated Updated JSPA Release Candidate Public Review Candidate Public Review

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

JAIN(tm) SIP Reference Implementation (RI) Specification Version 0.7

Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

●

1.0 Introduction

●

2.0 Objectives and scope

●

3.0 Initial set up for RI

●

4.0 Sending Events from Application through RI.

●

5.0 Limitations

●

6.0 Abbreviations

1.0 Introduction Java APIs for the Integrated Network (JAIN) Framework brings Service Portability and Network Convergence into the Telephony Network. JAIN encompasses a standard set of interfaces for service creation and a number of standard interfaces for service execution. This document, which is is part of the JAIN SIP 0.7 Specification, outlines the requirements of the JAIN SIP Reference Implementation.

2.0 Objectives and scope The purpose of this document is to ● Outline the requirements for setting up the Reference Implementation (RI) which JAIN SIP applications can run against. ● List the scope, limitations and restrictions of the JAIN SIP RI. The JAIN SIP RI will emulate the functions of a SIP stack (but will not be a SIP stack) in order to verify the requirements within this specification. The intention of the JAIN SIP RI is not to implement a SIP stack or to replace vendor SIP stacks. The purpose of the JAIN SIP RI is to provide a means to verify that JAIN SIP applications are compatible with the JAIN SIP specification. The RI can be used in order to help develop a JAIN SIP application. The JAIN SIP RI (here after referred to as RI) handles 'normal' SIP message sequencing, however, it performs some limited checking.

2.1 Support Software Several classes developed with JDK1.2 and the JAIN SIP API specification will be used while running the RI. This implementation will satisfy the following requirement as listed in the JAIN SIP Requirement Specification. REQ-RR-01-01: In order to execute the JAIN SIP Technology Compatibility Kit, or a JAIN SIP application, the following shall be required:

1. The Reference Implementation is utilised by implementing a JAIN SIP API specification. 2. Java Virtual Machine

3.0 Initial set up for RI The setup for the RI is initialised by a JAIN SIP Application. A diagram to illustrate the procedures involved on setting up the RI is shown in Figure 3.1. ● ●

●

●

●

●

When an application is present, it should invoke the getInstance method of the SipFactory. The pathname of the SipFactory is set to "com.dynamicsoft.ri" using the setPathName method (not strictly necessary since this is the default path name). The createSipStack method of the SipFactory is invoked. This returns a SipStack, i.e. an RI SIP Stack Implementation. The getListeningPoints method of the JainSipStack is called to get the ListeningPoints available (The RI will only return one ListeningPoint). The createSipProvider method of JainSipStack is then invoked. It returns the RI SIP Provider implementation which is attached to the Stack. The JAIN SIP application registers itself as an event listener of the RI's JAIN SIP Provider by invoking the addSipListener method of the provider. [see Figure 3.1].

Figure 3.1 JAIN SIP RI Initial Set Up After the initial setup, the JAIN SIP Application should be capable of sending and receiving Message Events to and from the RI, see Section 4.0.

4.0 Sending Events from Application through RI Messages are sent from the Application to the Provider using the appropriate sendXXX method. The RI simply passes clones of the message objects back to the registered Listener using the appropriate processXXX method. [See Figure 4.1]

Figure 4.1 JAIN SIP RI Message routing.

5.0 Limitations ● ● ● ●

Cannot handle multiple Providers Cannot handle multiple Listeners Does not include a SIP parser Does not send/receive messages to/from network

6.0 Abbreviations Abbreviations API

Application Programming Interface

TCK

Technology Capability Kit

JAIN

Java APIs for Integrated Network Framework

SIP

Session Initiation Protocol

TCP

Transmission Control Protocol

RI

Reference Implementation

UDP

User Datagram Protocol

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

JAIN(tm) SIP Technology Compatibility Kit (TCK) Specification Version 0.7 Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

●

1.0 Introduction

●

2.0 Objectives and scope

●

3.0 Initial set up for TCK

●

4.0 Sending Events from Listener to Provider

●

5.0 Test Results

●

6.0 Test Cases

●

7.0 Appendix

●

8.0 Abstract

1.0 Introduction Java APIs for the Intelligent Network (JAIN) Framework brings Service Portability and Network Convergence into the Telephony Network. JAIN encompasses a standard set of interfaces for service creation and a number of standard interfaces for service execution. This document, which is is part of the JAIN SIP 0.7 Specification, outlines the requirements of the JAIN SIP Technology Compatability Kit.

2.0 Objectives and scope The purpose of this document is to detail the test cases, for the Technology Compatibility Kit relevant to the JAIN SIP API Protocol. The Technology Compatibility Kit (TCK) tests an implementation of the JAIN SIP interfaces for compliance with the JAIN SIP Specification. The purpose of the JAIN SIP TCK is to verify that a Java SIP implementation is compatible with the JAIN SIP API Specification. The test cases outlined in this document are based on the JAIN SIP API Specification requirements that are specific to the remit of the TCK. This document also details the initial architectural set up required for the TCK. The TCK will have also have the ability to run against the JAIN SIP Reference Implementation (RI). The RI will emulate the functions of a SIP stack (but will not be a SIP stack) in order to verify the requirements in this specification. The intention of the RI is not to implement a SIP stack or to replace vendor SIP stacks. The purpose of the RI is to provide a means to verify that JAIN applications are compatible with their appropriate JAIN specification. The requirements for the RI are outlined in the JAIN SIP API Reference Implementation Requirements Specification document.

2.1 Support Software A test program written using JDK1.2 will be used during the tests. It is necessary to apply the

following requirements as listed in the JAIN SIP Requirements Specification. REQ-RR-01-01: In order to execute the JAIN SIP Technology Compatibility Kit, or a JAIN SIP application, the following shall be required:

1. The JAIN SIP API specification is implemented over a JAIN compliant protocol stack or over the Reference Implementation. 2. Java Virtual Machine

3.0 Initial set up for TCK ●

●

● ● ●

●

●

The TCK has a Log file which is created when you exit from the TCK. The log file can be found in the directory from where it was started. The name of the file will look simillar to this "SipReport-V0.6-20000717154751" The number at the end is Year, Month, Day of month, Hour, Min, Second. To create this report, firstly run the TCK, once this is done click the Report button, then exit the report window "TCK Output Results". Finally exit the TCK and the log file will be created. The TestSuite class and the JAIN TCK Listener are supplied by the TCK. The Listener implements the SipListener interface. From the TestSuite JAVA class a JAIN TCK Listener is instantiated. The user shall be prompted for the path name of the JAIN SIP implementation. The getInstance method of the Singleton SipFactory object is invoked. The createSipStack method of the SipFactory instance is invoked. This method returns the SipStackImpl, i.e. the SIP Stack Implemenatation. The createSipProvider method of SipStackImpl is invoked. It returns the Vendor's SipProvider implementation. The Provider registers the Listener implementation as an Event Listener, using the addSipListener method of the Vendor's implementation of the SipProvider interface, [see Figure 3.1].

Figure 3.1 JAIN SIP API TCK Initial Set Up The TCK interfaces with either the Reference Implementation (RI) or a Vendor Specific Implementation of the JAIN SIP API. The RI or the Vendor Specific Implementation will be refered to as the vendor throughout the document. After the initial setup, the JAIN TCK Listener should be capable of sending and receiving Events, see Section 4.0. The TCK test cases can then be run.

4.0 Sending Events from Listener to Provider 4.1 Caller and callee addresses Messages are sent from the Listener to the Provider and addressed to the callee. The callee's

address is the same as the caller's address except for the user name. The TCK uses the following addresses (with the host, port and transport being determined by the first ListeningPoint of the SipStack implementation): sip:caller@:;transport= sip:callee@:;transport= Therefore any messages sent from the Listener will be expected to be routed through the SIP stack and back to the same Listener (i.e. the caller). The messages will be passed from the Listener to the SipProvider Implementation and into the SIP stack. These messages are considered local to the SIP stack because the destination node has the same IP address as the SIP stack. In effect the TCP or UDP layer of the SIP stack will recognise that the messages are local and pass the messages back up the stack to the Provider. The messages are then routed back to the Listener. [See Figure 4.1] Consequently as messages travel only as far as the TCP or UDP layer before they are routed back up the SIP stack, and only one SIP stack is required in order to run the TCK test cases.

Figure 4.1 JAIN SIP API TCK Message routing.

4. 2 Method invocations ●

●

The TCK Listener both creates Messages and lets the Provider create Messages via the Provider's appropriate sendXXX method. The manner in which the Provider's implementation handles the received Messages in order to

●

●

interface with the SIP stack is the responsibility of the Vendor. To pass received a Message to the Listener the Provider will be required to invoke the Listener's appropriate processXXX method. The Listener appropriately handles the received Messages according to the test case being run.

5.0 Test Results As a result of the running the TCK a Test Report is produced. The TCK report includes a success status for each test. In addition a detailed execution trace will be output. If all test cases are passed the JAIN SIP Implementation will be considered JAIN Compliant. REQ-CR-01-01: A JAIN SIP Implementation shall be compatible after passing the TCK.

6.0 Test Cases Many of the Test Cases, which are based on the JAIN SIP API specification requirements applicable to the scope of the TCK, will be effectively passed if the TCK setup architecture is adhered to and Messages can be routed successfully from Listener to destination. However the test cases outlined will individually test all appropriate aspects of the TCK and a report will be generated. The JAIN SIP TCK will only test a 1:1 Provider / Listener relationship. A future release of the JAIN SIP TCK may test a multiple Provider / Listener relationship. The test cases in this section consist of a Test Case name and a reference number, Test purpose and a Test result required for a success. Test Type

Test Reference

Set Up Configuration

6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7, 6.8, 6.9, 6.10, 6.11, 6.12

Message Sending

6.13, 6.14, 6.15, 6.16, 6.17, 6.18, 6.19, 6.20, 6.21, 6.22

Message implementations (plus MessageFactory)

6.23

Header implementations (plus HeaderFactory)

6.24

Address implementations (plus AddressFactory)

6.25

Table 6.1 Test Case categories The TCK Test Report [see section 5.0] will individually list results based on each test case.

Test Reference Test Case 6.1

Stack can store stack name

6.2

Stack has at least one ListeningPoint

6.3

Stack has no Providers when created

6.4

Stack can create Provider

6.5

Stack cannot create multiple Providers using same ListeningPoint

6.6

Stack cannot create Provider with listeningPoint it does not own

6.7

Stack can remove Provider

6.8

Stack throws IllegalArgumentExceptions if null argument is passed to any of its methods

6.9

Provider has reference to its Stack

6.10

Provider has reference to its ListeningPoint

6.11

Provider can add Listener

6.12

Provider can remove Listener

6.13

Provider generates new CallIdHeaders correctly

6.14

Provider generates new CSeq numbers correctly

6.15

Provider returns Messages to Listener equal to messages Listener sent

6.16

Provider maps transaction ids to Messages correctly

6.17

Provider constructs Messages correctly

6.18

Provider handles unrecognised methods and headers

6.19

Provider throws TransactionDoesNotExistException if user refers to a non-existent transaction

6.20

Provider throws IllegalArgumentException if null argument is passed to any of its methods

6.21

Provider only sends ACK Request if success Response has been received for corresponding INVITE Request

6.22

Provider only sends CANCEL Request if no final Response has been received for corresponding Request

6.23

Message and MessageFactory interfaces exhibit correct API-defined behaviour

6.24

Header and HeaderFactory interfaces exhibit correct API-defined behaviour

6.25

Address and AddressFactory interfaces exhibit correct API-defined behaviour Table 6.2 Test Case Index

6.1 Test Case 1 Stack can store stack name 6.1.1 Test purpose Verify that the implementation of SipStack can store a stack name as given by the user. 6.1.1 Test procedure The TCK attempts to set the stack name of the SipStack implementation using the setStackName method, retrieves the value using the getStackName method, and then compares the two values. 6.1.3 Test result The test result is true if the value returned by the getStackName method is equal to the value passed to the setStackName method; false otherwise.

6.2 Test Case 2 Stack has at least one ListeningPoint 6.2.1 Test purpose Verify that the implementation of SipStack has at least one ListeningPoint when created (since adding ListeningPoints is not allowed in the JAIN SIP API). 6.2.2 Test procedure The TCK attempts to retrieve the ListeningPoints owned by the SipStack implementation by calling the getListeningPoints method. 6.2.3 Test result The test result is true if the method returns an Iterator of one or more ListeningPoints. The test result is false if the method throws a ListeningPointUnavailableException, or if it returns null or an empty Iterator of ListeningPoints. 6.3 Test Case 3 Stack has no Providers when created 6.3.1 Test purpose Verify that the implementation of SipStack has no SipProviders attached when it is created. 6.3.2 Test procedure The TCK attempts to retrieve the SipStack implementation's list of SipProviders using the getSipProviders method.

6.3.3 Test result The test result is true if the method returns null, indicating that there are no JainSipProviders attached. The test result is false otherwise.

6.4 Test Case 4 Stack can create Provider. 6.4.1 Test purpose Verify that the implementation of SipStack can create a SipProvider object. 6.4.2 Test procedure The TCK attempts to create a SipProvider object by calling the createSipProvider method of the SipStack implementation. (The TCK uses the first ListeningPoint of the SipStack as the argument to the method). The TCK then attempts to retrieve the SipStack implementation's list of SipProviders using the getSipProviders method. 6.4.3 Test result The test result is true if the createSipProvider method throws no Exception, returns a SipProvider, and the getSipProviders method returns an Iterator of SipProviders containing only the SipProvider returned from the createSipProvider method. The test result is false if either method throws an Exception, if the createSipProvider method returns null, or if the getSipProviders method returns null, an empty Iterator, an Iterator containing the wrong object, or an Iterator with more than one element.

6.5 Test Case 5 Stack cannot create multiple Providers using same ListeningPoint 6.5.1 Test purpose Verify that the implementation of SipStack cannot create multiple SipProvider objects based on the same ListeningPoint. 6.5.2 Test procedure The TCK attempts to create another SipProvider object by calling the createSipProvider method of the SipStack implementation. (The TCK uses the first ListeningPoint of the SipStack again as the argument to the method). The TCK then attempts to retrieve the SipStack implementation's list of SipProviders using the getSipProviders method. 6.5.3 Test result The test result is only true if the createSipProvider method throws a ListeningPointUnavailableException and the getSipProviders method returns an Iterator containing only the first SipProvider created. Test result is false otherwise.

6.6 Test Case 6 Stack cannot create Provider with ListeningPoint it does not own 6.6.1 Test purpose Verify that the implementation of SipStack cannot create SipProvider objects based ListeningPoint it does not own. 6.6.2 Test procedure The TCK attempts to create another SipProvider object by calling the createSipProvider method of the SipStack implementation. (The TCK uses a new ListeningPoint with a port one higher than the port of the first ListeningPoint of the SipStack as the argument to the method). The TCK then attempts to retrieve the SipStack implementation's list of SipProviders using the getSipProviders method. 6.6.3 Test result The test result is only true if the createSipProvider method throws a ListeningPointUnavailableException and the getProviders method returns null. Test result is false otherwise.

6.7 Test Case 7 Stack can remove Provider 6.7.1 Test purpose Verify that the implementation of SipStack can remove a SipProvider object. 6.7.2 Test procedure The TCK attempts to remove a SipProvider object by calling the removeSipProvider method of the SipStack implementation. (The TCK uses the first SipProvider created as the argument to the method). The TCK then attempts to retrieve the SipStack implementation's list of SipProviders using the getSipProviders method. (Note that the TCK creates another SipProvider based on the first ListeningPoint of the SipStack after this test - for use in later tests) 6.7.3 Test result The test result is only true if the removeSipProvider method throws no Exception and the getSipProviders method returns null indicating there are no longer any SipProviders. Test result is false otherwise.

6.8 Test Case 8 Stack throws IllegalArgumentExceptions if null argument is passed to any of its methods 6.8.1 Test purpose

Verify that the implementation of SipStack throws IllegalArgumentExceptions whenever a null argument is passed to any of its methods. 6.8.2 Test procedure The TCK calls every method of the SipStack implementation that takes an Object as an argument, passing null instead of an Object in each case. The TCK keeps track of the number of method calls made, and the number of IllegalArgumentExceptions thrown. 6.8.3 Test result The test result is only true if the number of method calls equals the number of IllegalArgumentExceptions thrown. The test result is false otherwise.

6.9 Test Case 9 Provider has reference to its Stack 6.9.1 Test purpose Verify that the implementation of SipProvider maintains a reference to the SipStack it is associated with. 6.9.2 Test procedure The TCK calls the getSipStack method of the SipProvider implementation and compares the result with the SipStack object that was used to create the SipProvider. 6.9.3 Test result The test result is true only if the result of the getSipStack method is equal to the SipStack implementation used to create the SipProvider. The test result is false otherwise.

6.10 Test Case 10 Provider has reference to its ListeningPoint 6.10.1 Test purpose Verify that the implementation of SipProvider maintains a reference to the ListeningPoint it is associated with. 6.10.2 Test procedure The TCK calls the getListeningPoint method of the SipProvider implementation and compares the result with the ListeningPoint object that was used to create the SipProvider. 6.10.3 Test result The test result is true only if the result of the getListeningPoint method is equal to the ListeningPoint used to create the SipProvider. The test result is false otherwise.

6.11 Test Case 11 Provider can add Listener 6.11.1 Test purpose Verify that the implementation of SipProvider can add a SipListener to itself. 6.11.2 Test procedure The TCK Sender attempts to add itself as a SipListener to the SipProvider implementation using its addSipListener method. 6.11.3 Test result The test result is true if no Exception is thrown by the addSipListener method. The test result is false otherwise.

6.12 Test Case 12 Provider can remove Listener 6.12.1 Test purpose Verify that the implementation of SipProvider can remove a SipListener from itself. 6.12.2 Test procedure The TCK Sender attempts to remove itself as a SipListener from the SipProvider implementation using its removeSipListener method. 6.12.3 Test result The test result is true if no Exception is thrown by the removeSipListener method. The test result is false otherwise.

6.13 Test 13 Provider generates new CallIdHeaders correctly 6.13.1 Test purpose Verify that the implementation of SipProvider can generate new CallIdHeaders correctly. 6.13.2 Test procedure The TCK attempts to retrieve two new CallIdHeaders generated by the SipProvider implementation by calling its getNewCallIdHeader method twice consecutively and storing the results of the two calls.

6.13.3 Test result The test result is true only if the two method calls throw no Exceptions, and return CallIdHeaders with different values. The test result is false otherwise..

6.14 Test 14 Provider generates new CSeq numbers correctly. 6.14.1 Test purpose Verify that the implementation of SipProvider can generate new CSeq numbers correctly. 6.14.2 Test procedure The TCK attempts to retrieve two new CSeq numbers generated by the SipProvider implementation by calling its getNewCSeqHeader method twice consecutively and storing the results of the two calls. (Note the first CallIdHeader generated in test 6.13 is passed as the argument to both method calls). 6.14.3 Test result The test result is true only if the two method calls throw no Exceptions, return two positive numbers, and the second number is one greater than the first. The test result is false otherwise.

6.15 Test 15 Provider returns Messages to Listener equal to messages Listener sent 6.15.1 Test purpose Verify that the implementation of SipProvider returns Messages to Listener that are equal to the Messages sent. This checks the implementation's construction of Messages is correct. 6.15.2 Test procedure The TCK will keep an separate ordered lists of all sent and received Messages throughout the duration of the tests. The lists are compared after all tests have been executed. 6.15.3 Test result The test result is true if the number of sent Messages equals the number of received Messages, and each received Message equals its corresponding sent Message. (They are compared using the equals method of the Message class). The test result is false otherwise.

6.16 Test Case 16 Provider maps transaction ids to Messages correctly 6.16.1 Test purpose

Verify that the implementation of SipProvider maps transaction ids to Messages correctly. 6.16.2 Test procedure The TCK constructs one of each type of Message (e.g. INVITE Request) and calls its corresponding send method (e.g. sendRequest) that takes a user-constructed Message. Then the TCK attempts to retrieve the Message associated with the transaction id returned by the send method (using getTransaction{Request|Response} methods). The constructed and retrieved Messages are then compared. 6.16.3 Test result The test result is true only if none of the method calls throw an Exception, and each constructed Message is equal to the retrieved Message. (They are compared using the equals method of the Message class). The test result is false otherwise.

6.17 Test Case 17 Provider constructs Messages correctly 6.17.1 Test purpose Verify that the implementation of SipProvider constructs Messages correctly. 6.17.2 Test procedure The TCK constructs one of each type of Message (e.g. CANCEL Request) and calls its corresponding send method (e.g. sendCancel) that creates a Message automatically. Then the TCK attempts to retrieve the automatically constructed Message associated with the transaction id returned by the send method (using getTransaction{Request|Response} methods). The user-constructed and provider-constructed Messages are then compared. 6.17.3 Test result The test result is true only if none of the method calls throw an Exception, and each user-constructed Message is equal to the provider-constructed Message. (They are compared using the equals method of the Message class). The test result is false otherwise.

6.18 Test Case 18 Provider handles unrecognised methods and headers 6.18.1 Test purpose Verify that the implementation of SipProvider can handle unrecognised methods and headers. This essentially tests the implementations handling of generic Message and Header classes. 6.18.2 Test procedure The TCK constructs three Messages as follows:

One with recognised Headers and an unrecognised method. ● One with an unrecognised Header and a recognised method. ● One with an unrecognised Header and an unrecognised method. The TCK then attempts to send these Messages using the appropriate send method of the SipProvider implementation. ●

6.18.3 Test result The test result is only true if no method calls throw an Exception, and the Messages are received as sent. The test result is false otherwise.

6.19 Test Case 19 Provider throws TransactionDoesNotExistException if user refers to a non-existent transaction 6.19.1 Test purpose Verify that the implementation of SipProvider throws a TransactionDoesNotExistException if a user attempts to refer to a non-existent transaction. 6.19.2 Test procedure The TCK attempts to invoke each method on the SipProvider implementation that takes either a client or server transaction id as a parameter. The TCK uses a transaction id that it knows has not been used by the SipProvider implementation. Since transaction ids are positive integers, a negative integer is the appropriate choice for the TCK to use as a transaction id. The TCK keeps count of the number of method calls and the number of TransactionDoesNotExistExceptions thrown. 6.19.3 Test result The test result is true only if the number of method calls equals the number of TransactionDoesNotExistExceptions thrown. The test result is false otherwise.

6.20 Test Case 20 Provider throws IllegalArgumentException if null argument is passed to any of its methods 6.20.1 Test purpose Verify that the implementation of SipProvider throws IllegalArgumentExceptions whenever a null argument is passed to any of its methods. 6.20.2 Test procedure

The TCK calls every method of the SipProvider implementation that takes an Object as an argument, passing null instead of an Object in each case. The TCK keeps track of the number of method calls made, and the number of IllegalArgumentExceptions thrown. 6.20.3 Test result The test result is only true if the number of method calls equals the number of IllegalArgumentExceptions thrown. The test result is false otherwise.

6.21 Test Case 21 Provider only sends an ACK Request if success Response has been received for corresponding INVITE Request 6.21.1 Test purpose Verify that the implementation of SipProvider only sends an ACK Request if a success Response has been received for a corresponding Invite. 6.21.2 Test procedure The TCK attempts to send ACK Requests in the following situations: ● A non-success Response has been received for a corresponding INVITE Request ● A success Response has been received for a corresponding Request that is not an INVITE Request ● A non-success Response has been received for a corresponding Request that is not an INVITE Request ● A success Response has been received for a corresponding INVITE Request 6.21.3 Test result The test result is only true if a SipException is thrown in the first three sendAck method calls, and no Exception is thrown in the fourth sendAck method call. The test result is false otherwise.

6.22 Test Case 22 Provider only sends a CANCEL Request if no final Response has been received for corresponding Request 6.22.1 Test purpose Verify that the implementation of SipProvider only sends a CANCEL Request if a no final Response has been received for a corresponding Request. 6.22.2 Test procedure The TCK attempts to send CANCEL Requests in the following situations:

● ● ●

No Response has been received for a corresponding Request A provisional Response has been received for a corresponding Request A final Response has been received for a corresponding Request

6.22.3 Test result The test result is only true if no Exception is thrown in the first two sendCancel method calls, and a SipException is thrown in the third sendCancel method call. The test result is false otherwise.

6.23 Test Case 23 Message implementations (plus MessageFactory) exhibit correct API-defined behaviour 6.22.1 Test purpose Verify implementations of Message and MessageFactory interfaces exhibit correct API-defined behaviour 6.22.2 Test procedure The TCK uses the MessageFactory implementation to create Messages. It uses combinations of null, invalid and valid arguments for the MessageFactory's create methods. It checks Exceptions are thrown when they should, and not thrown when they shouldn't. It also checks that the Messages returned contain the correct field values. Then the Message implementations are tested by calling all methods - again with combinations of null, invalid and valid arguments. 6.22.3 Test result The test result is only true if the MessageFactory and Message implementations exhibit correct API-defined behaviour.

6.24 Test Case 24 Header implementations (plus HeaderFactory) exhibit correct API-defined behaviour 6.22.1 Test purpose Verify implementations of Header and HeaderFactory interfaces exhibit correct API-defined behaviour 6.22.2 Test procedure The TCK uses the HeaderFactory implementation to create Headers. It uses combinations of null, invalid and valid arguments for the HeaderFactory's create methods. It checks Exceptions are thrown when they should, and not thrown when they shouldn't. It also checks that the

Headers returned contain the correct field values. Then the Header implementations are tested by calling all methods - again with combinations of null, invalid and valid arguments. 6.22.3 Test result The test result is only true if the HeaderFactory and Header implementations exhibit correct API-defined behaviour.

6.25 Test Case 25 Address implementations (plus AddressFactory) exhibit correct API-defined behaviour 6.22.1 Test purpose Verify implementations of address(URI, SipURL, NameAddress) and AddressFactory interfaces exhibit correct API-defined behaviour 6.22.2 Test procedure The TCK uses the AddressFactory implementation to create addresses. It uses combinations of null, invalid and valid arguments for the AddressFactory's create methods. It checks Exceptions are thrown when they should, and not thrown when they shouldn't. It also checks that the addresses returned contain the correct field values. Then the address implementations are tested by calling all methods - again with combinations of null, invalid and valid arguments. 6.22.3 Test result The test result is only true if the AddressFactory and address implementations exhibit correct API-defined behaviour.

7.0 Appendix Abbreviations API

Application Programming Interface

TCK

Technology Capability Kit

JAIN

Java APIs for Integrated Network Framework

SIP

Session Initiation Protocol

TCP

Transmission Control Protocol

RI

Reference Implementation

UDP

User Datagram Protocol

8.0 Abstract This document details the Technology Capability Kit specification requirements for which an implementation of JAIN interfaces must pass in order to be considered compliant to the JAIN Specification. The purpose of the JAIN TCK is to verify that a Java SIP protocol implementation is compatible to the JAIN SIP Specification.

Copyright - 2000 Sun Microsystems If you have any comments or queries, please mail them to [email protected]

All Classes

Packages jain.protocol.ip.sip jain.protocol.ip.sip.header jain.protocol.ip.sip.message

JAIN(tm) SIP API All Classes AcceptEncodingHeader AcceptHeader AcceptLanguageHeader AddressFactory AllowHeader AuthorizationHeader CallIdHeader ContactHeader ContentEncodingHeader ContentLengthHeader ContentTypeHeader CSeqHeader DateHeader EncodingHeader EncryptionHeader EndPointHeader ExpiresHeader FromHeader Header HeaderFactory HeaderIterator HeaderParseException HideHeader ListeningPoint ListeningPointUnavailableException MaxForwardsHeader Message MessageFactory

Standard Java(tm) Interface to the Session Initiation Protocol (SIP) Release 0.7 Copyrights

See: Description

Packages jain.protocol.ip.sip

This package contains the main interfaces required to represent JAIN SIP protocol stacks, JAIN SIP applications, as well as the classes and exceptions needed to send and receive JAIN SIP messages.

jain.protocol.ip.sip.header

This package contains the classes representing SIP headers.

jain.protocol.ip.sip.message This package contains the Event classes representing SIP Messages.

Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS

NameAddress NameAddressHeader OptionTagHeader OrganizationHeader Parameters ParametersHeader PriorityHeader ProductHeader ProxyAuthenticateHeader ProxyAuthorizationHeader ProxyRequireHeader RecordRouteHeader Request RequireHeader Response ResponseKeyHeader RetryAfterHeader RouteHeader SecurityHeader ServerHeader SipException SipFactory SipListener SipListenerAlreadyRegisteredException SipListenerNotRegisteredException SipParseException SipPeerUnavailableException SipProvider SipStack SipURL SubjectHeader TimeStampHeader ToHeader TransactionDoesNotExistException UnableToDeleteProviderException UnsupportedHeader URI UserAgentHeader ViaHeader

Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

This document provides an overview of the JAIN SIP API, which is part of the JAIN SIP 0.7 Specification. It is not a tutorial, readers should have a good understanding of SIP and be comfortable reading the JAIN SIP API. This document, combined with the JAIN SIP API Requirements Specification, the JAIN SIP Reference Implementation (RI) Specification and the JAIN SIP Technology Compatability Kit (TCK) Specification (described below) comprise the JAIN SIP 0.7 Specification.

The JAIN SIP API Requirements Specification The Requirements Specification provides a high level overview of JAIN and the JAIN SIP API Specification as well as explaining the JAIN Architecture, and the functionality provided by each of the requirements defined within the document.

The JAIN SIP Reference Implementation (RI) Specification The JAIN SIP Reference Implementation (RI) is a an example Java program that emulates the functions of a SIP stack in order to verify that JAIN SIP applications are compatible with the JAIN SIP specification. The RI can therefore be used to help develop and debug a JAIN SIP application in the absence of an JAIN SIP Compliant SIP Stack. The purpose of the the RI Specification is to outline the requirements for setting up the RI and to list the scope, limitations and restrictions of the RI.

WarningHeader WWWAuthenticateHeader

The JAIN SIP Technology Compatibility Kit (TCK) Specification The purpose of the JAIN SIP TCK is to verify that a JAIN SIP implementation is compatible with the JAIN SIP API Specification. The TCK Specification details the test cases which an implementation of JAIN interfaces must pass in order to be considered compliant with the JAIN SIP Specification.

Overview of JAIN SIP API The implementation of this API focuses around the SipListener and SipProvider interfaces.A Listener could be any SIP User application, and would use a Provider to send SIP messages into the network. To send a SIP message, a Listener would send Messages to a SipProvider. The SipProvider interface defines the methods required to send SIP messages. This interface also defines the methods required to maintain a list of SipListeners. An implementation of this interface would listen for SIP messages from the stack and forward these messages to its registered SipListeners. The SIP messages would be sent as part of SipEvents (which also include the associated transaction id).

Diagram 1 - Jain SIP message passing

An object implementing the SipProvider interface would be vendor specific and would act as a proxy for a ListeningPoint of a SipStack. Zero or more SipListeners could register with a SipProvider, however the JAIN SIP API provides the ability to limit the number of SipListeners that may register at any one time.

Diagram 2 - SipListener registration with multiple SipProviders The SipProvider interface defines the methods required to process any of the SipEvents sent from a Provider. An object implementing the SipListener interface would register as a SipListener of a SipProvider and would subsequently be able to receive SipEvents from that SipProvider. When a received SIP message arrives at the SIP Stack, the SipProvider forwards the SIP message as SipEvents to its registered SipListeners. Diagram 4.0 illustrates how a SipEvent is distributed to SipListeners.

Diagram 3 - SipEvent Distribution

A JAIN SIP example The following points illustrate how the JAIN SIP API can be used to send and receive SIP Messages. The example looks at the code of a Jain SIP User application and the steps the User application will use to create a SipProvider for communicating with the proprietary SIP stack. import import import import

jain.protocol.ip.sip.*; jain.protocol.ip.sip.header.*; jain.protocol.ip.sip.message.*; java.util.*;

public class Example implements SipListener { private SipFactory sipFactory = null; private AddressFactory addressFactory = null; private HeaderFactory headerFactory = null; private MessageFactory messageFactory = null; private SipStack sipStack = null; private SipProvider sipProvider = null; private ListeningPoint[] listeningPoints = null; // Main public static void main(String[] args)

{ Example example = new Example(); example.sendMessages(); } public Example() { setup(); } private void setup() { // Obtain an instance of the singleton SipFactory sipFactory = SipFactory.getInstance(); // Set path name of SipFactory to reference implementation // (not needed - default path name) sipFactory.setPathName("com.dynamicsoft.ri"); try { // Create SipStack object sipStack = (SipStack)sipFactory.createSipStack(); } catch(SipPeerUnavailableException e) { // could not find com.dynamicsoft.ri.jain.protocol.ip.sip.SipStackImpl // in the classpath System.err.println(e.getMessage()); System.exit(0); } // Set name of SipStack sipStack.setStackName("Reference Implementation SIP stack"); // Try to get the SipStack's ListeningPoints and create a // SipProvider based on the first ListeningPoint try { listeningPoints = sipStack.getListeningPoints(); sipProvider = sipStack.createSipProvider((ListeningPoint)listeningPoints.next()); } catch(NullPointerException e) {

System.err.println("Stack has no ListeningPoints"); System.exit(0); } catch(ListeningPointUnavailableException e) { System.err.println(e.getMessage()); System.exit(0); } // Register this application as a SipListener of the SipProvider try { sipProvider.addSipListener(this); } catch(TooManyListenersException e) { // A limit has been reached on the number of Listeners allowed per provider System.err.println(e.getMessage()); System.exit(0); } catch(SipListenerAlreadyRegisteredException e) { // Already been added as SipListener System.err.println(e.getMessage()); System.exit(0); } } // Process transaction timeout public void processTimeOut(String transactionId, boolean isServerTransaction) { System.out.println("Transaction " + transactionId + " timed out"); } // Process Request received public void processRequest(String serverTransactionId, Request request) { System.out.println("Request received with server transaction id " + serverTransactionId + ":\n" + request); }

// Process of Response received public void processResponse(String clientTransactionId, Response response) { System.out.println("Response received with client transaction id " + clientTransactionId + ":\n" + response); try { // Get method of respose String method = response.getCSeqHeader().getMethod(); // Get status code of response int statusCode = response.getStatusCode(); // If response is a 200 INVITE response, try to send an ACK if((statusCode == Response.OK) && (method.equals(Request.INVITE))) { sipProvider.sendAck(clientTransactionId); } } catch(SipException e) { System.err.println(e.getMessage()); System.exit(0); } } public void sendMessages() { // Create INVITE Request to send SipURL fromAddress = null; NameAddress fromNameAddress = null; FromHeader fromHeader = null; SipURL toAddress = null; NameAddress toNameAddress = null; ToHeader toHeader = null; SipURL requestURI = null; CallIdHeader callIdHeader = null; CSeqHeader cSeqHeader = null; ViaHeader viaHeader = null; ArrayList viaHeaders = null; ContentTypeHeader contentTypeHeader = null;

Request request = null; try { // create From Header addressFactory.createSipURL("caller", sipProvider.getListeningPoint().getHost()); fromAddress.setPort(sipProvider.getListeningPoint().getPort()); fromNameAddress = addressFactory.createNameAddress("Caller", fromAddress); fromHeader = headerFactory.createFromHeader(fromNameAddress); // create To Header addressFactory.createSipURL("callee", sipProvider.getListeningPoint().getHost()); toAddress.setPort(sipProvider.getListeningPoint().getPort()); toNameAddress = addressFactory.createNameAddress("Callee", fromAddress); toHeader = headerFactory.createToHeader(fromNameAddress); // create Request URI requestURI = (SipURL)toAddress.clone(); requestURI.setTransport(sipProvider.getListeningPoint().getTransport()); // Create CallIdHeader callIdHeader = sipProvider.getNewCallIdHeader(); // Create CSeqHeader sipProvider.getNewCSeqHeader(callIdHeader, fromHeader, toHeader, Request.INVITE); // Create ViaHeaders viaHeader = headerFactory.createViaHeader(sipProvider.getListeningPoint().getHost(), sipProvider.getListeningPoint().getPort(), sipProvider.getListeningPoint().getTransport()); viaHeaders = new ArrayList(); viaHeaders.add(viaHeader); // Create ContentTypeHeader contentTypeHeader =

headerFactory.createContentTypeHeader("application", "sdp"); // Create INVITE Request request = messageFactory.createRequest(requestURI, Request.INVITE, callIdHeader, cSeqHeader, fromHeader, toHeader, viaHeaders, "body", contentTypeHeader); } catch(SipParseException e) { // Implementation was unable to parse a value System.err.println(e.getMessage() + "[" + e.getUnparsable() + "]"); System.exit(0); } catch(SipException e) { // Another exception occurred System.err.println(e.getMessage()); System.exit(0); } // Send Message String clientTransactionId = null;; try { // Send INVITE Request clientTransactionId = sipProvider.sendRequest(request); } catch(SipException e) { // SipProvider could not send INVITE Request System.err.println(e.getMessage()); System.exit(0); } } }

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

JAIN(tm) SIP API Standard Java(tm) Interface to the Session Initiation Protocol (SIP) Release 0.7 Copyrights

See: Description

Packages jain.protocol.ip.sip

This package contains the main interfaces required to represent JAIN SIP protocol stacks, JAIN SIP applications, as well as the classes and exceptions needed to send and receive JAIN SIP messages.

jain.protocol.ip.sip.header

This package contains the classes representing SIP headers.

jain.protocol.ip.sip.message This package contains the Event classes representing SIP Messages.

Copyrights Copyright - 2000 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94043, U.S.A. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

This document provides an overview of the JAIN SIP API, which is part of the JAIN SIP 0.7 Specification. It is not a tutorial, readers should have a good understanding of SIP and be comfortable reading the JAIN SIP API. This document, combined with the JAIN SIP API Requirements Specification, the JAIN SIP Reference Implementation (RI) Specification and the JAIN SIP Technology Compatability Kit (TCK) Specification (described below) comprise the JAIN SIP 0.7 Specification.

The JAIN SIP API Requirements Specification The Requirements Specification provides a high level overview of JAIN and the JAIN SIP API Specification as well as explaining the JAIN Architecture, and the functionality provided by each of the requirements defined within the document.

The JAIN SIP Reference Implementation (RI) Specification The JAIN SIP Reference Implementation (RI) is a an example Java program that emulates the functions of a SIP stack in order to verify that JAIN SIP applications are compatible with the JAIN SIP specification. The RI can therefore be used to help develop and debug a JAIN SIP application in the absence of an JAIN SIP Compliant SIP Stack. The purpose of the the RI Specification is to outline the requirements for setting up the RI and to list the scope, limitations and restrictions of the RI.

The JAIN SIP Technology Compatibility Kit (TCK) Specification The purpose of the JAIN SIP TCK is to verify that a JAIN SIP implementation is compatible with the JAIN SIP API Specification. The TCK Specification details the test cases which an implementation of JAIN interfaces must

pass in order to be considered compliant with the JAIN SIP Specification.

Overview of JAIN SIP API The implementation of this API focuses around the SipListener and SipProvider interfaces.A Listener could be any SIP User application, and would use a Provider to send SIP messages into the network. To send a SIP message, a Listener would send Messages to a SipProvider. The SipProvider interface defines the methods required to send SIP messages. This interface also defines the methods required to maintain a list of SipListeners. An implementation of this interface would listen for SIP messages from the stack and forward these messages to its registered SipListeners. The SIP messages would be sent as part of SipEvents (which also include the associated transaction id).

Diagram 1 - Jain SIP message passing An object implementing the SipProvider interface would be vendor specific and would act as a proxy for a ListeningPoint of a SipStack. Zero or more SipListeners could register with a SipProvider, however the JAIN SIP API provides the ability to limit the number of SipListeners that may register at any one time.

Diagram 2 - SipListener registration with multiple SipProviders The SipProvider interface defines the methods required to process any of the SipEvents sent from a Provider. An object implementing the SipListener interface would register as a SipListener of a SipProvider and would subsequently be able to receive SipEvents from that SipProvider. When a received SIP message arrives at the SIP Stack, the SipProvider forwards the SIP message as SipEvents to its registered SipListeners. Diagram 4.0 illustrates how a SipEvent is distributed to SipListeners.

Diagram 3 - SipEvent Distribution

A JAIN SIP example The following points illustrate how the JAIN SIP API can be used to send and receive SIP Messages. The example looks at the code of a Jain SIP User application and the steps the User application will use to create a SipProvider for communicating with the proprietary SIP stack. import import import import

jain.protocol.ip.sip.*; jain.protocol.ip.sip.header.*; jain.protocol.ip.sip.message.*; java.util.*;

public class Example implements SipListener { private SipFactory sipFactory = null; private AddressFactory addressFactory = null; private HeaderFactory headerFactory = null; private MessageFactory messageFactory = null; private SipStack sipStack = null; private SipProvider sipProvider = null; private ListeningPoint[] listeningPoints = null; // Main public static void main(String[] args) { Example example = new Example(); example.sendMessages(); } public Example() { setup(); } private void setup() { // Obtain an instance of the singleton SipFactory sipFactory = SipFactory.getInstance(); // Set path name of SipFactory to reference implementation // (not needed - default path name) sipFactory.setPathName("com.dynamicsoft.ri"); try { // Create SipStack object sipStack = (SipStack)sipFactory.createSipStack(); } catch(SipPeerUnavailableException e) {

// could not find com.dynamicsoft.ri.jain.protocol.ip.sip.SipStackImpl // in the classpath System.err.println(e.getMessage()); System.exit(0); } // Set name of SipStack sipStack.setStackName("Reference Implementation SIP stack"); // Try to get the SipStack's ListeningPoints and create a // SipProvider based on the first ListeningPoint try { listeningPoints = sipStack.getListeningPoints(); sipProvider = sipStack.createSipProvider((ListeningPoint)listeningPoints.next()); } catch(NullPointerException e) { System.err.println("Stack has no ListeningPoints"); System.exit(0); } catch(ListeningPointUnavailableException e) { System.err.println(e.getMessage()); System.exit(0); } // Register this application as a SipListener of the SipProvider try { sipProvider.addSipListener(this); } catch(TooManyListenersException e) { // A limit has been reached on the number of Listeners allowed per provider System.err.println(e.getMessage()); System.exit(0); } catch(SipListenerAlreadyRegisteredException e) { // Already been added as SipListener System.err.println(e.getMessage()); System.exit(0); } }

// Process transaction timeout public void processTimeOut(String transactionId, boolean isServerTransaction) { System.out.println("Transaction " + transactionId + " timed out"); } // Process Request received public void processRequest(String serverTransactionId, Request request) { System.out.println("Request received with server transaction id " + serverTransactionId + ":\n" + request); } // Process of Response received public void processResponse(String clientTransactionId, Response response) { System.out.println("Response received with client transaction id " + clientTransactionId + ":\n" + response); try { // Get method of respose String method = response.getCSeqHeader().getMethod(); // Get status code of response int statusCode = response.getStatusCode(); // If response is a 200 INVITE response, try to send an ACK if((statusCode == Response.OK) && (method.equals(Request.INVITE))) { sipProvider.sendAck(clientTransactionId); } } catch(SipException e) { System.err.println(e.getMessage()); System.exit(0); } } public void sendMessages() { // Create INVITE Request to send SipURL fromAddress = null;

NameAddress fromNameAddress = null; FromHeader fromHeader = null; SipURL toAddress = null; NameAddress toNameAddress = null; ToHeader toHeader = null; SipURL requestURI = null; CallIdHeader callIdHeader = null; CSeqHeader cSeqHeader = null; ViaHeader viaHeader = null; ArrayList viaHeaders = null; ContentTypeHeader contentTypeHeader = null; Request request = null; try { // create From Header addressFactory.createSipURL("caller", sipProvider.getListeningPoint().getHost()); fromAddress.setPort(sipProvider.getListeningPoint().getPort()); fromNameAddress = addressFactory.createNameAddress("Caller", fromAddress); fromHeader = headerFactory.createFromHeader(fromNameAddress); // create To Header addressFactory.createSipURL("callee", sipProvider.getListeningPoint().getHost()); toAddress.setPort(sipProvider.getListeningPoint().getPort()); toNameAddress = addressFactory.createNameAddress("Callee", fromAddress); toHeader = headerFactory.createToHeader(fromNameAddress); // create Request URI requestURI = (SipURL)toAddress.clone(); requestURI.setTransport(sipProvider.getListeningPoint().getTransport()); // Create CallIdHeader callIdHeader = sipProvider.getNewCallIdHeader(); // Create CSeqHeader sipProvider.getNewCSeqHeader(callIdHeader, fromHeader, toHeader, Request.INVITE); // Create ViaHeaders viaHeader = headerFactory.createViaHeader(sipProvider.getListeningPoint().getHost(), sipProvider.getListeningPoint().getPort(),

sipProvider.getListeningPoint().getTransport()); viaHeaders = new ArrayList(); viaHeaders.add(viaHeader); // Create ContentTypeHeader contentTypeHeader = headerFactory.createContentTypeHeader("application", "sdp"); // Create INVITE Request request = messageFactory.createRequest(requestURI, Request.INVITE, callIdHeader, cSeqHeader, fromHeader, toHeader, viaHeaders, "body", contentTypeHeader); } catch(SipParseException e) { // Implementation was unable to parse a value System.err.println(e.getMessage() + "[" + e.getUnparsable() + "]"); System.exit(0); } catch(SipException e) { // Another exception occurred System.err.println(e.getMessage()); System.exit(0); } // Send Message String clientTransactionId = null;; try { // Send INVITE Request clientTransactionId = sipProvider.sendRequest(request); } catch(SipException e) { // SipProvider could not send INVITE Request System.err.println(e.getMessage()); System.exit(0); } } }

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

Package jain.protocol.ip.sip This package contains the main interfaces required to represent JAIN SIP protocol stacks, JAIN SIP applications, as well as the classes and exceptions needed to send and receive JAIN SIP messages. See: Description

Interface Summary AddressFactory This interface provides factory methods to allow an application create address objects from a particular JAIN SIP implementation. ListeningPoint This interface represents a unique IP network listening point, and consists of host, port and transport NameAddress

This interface represents a user's display name and address.

Parameters

This interface represents a list of parameters.

SipListener

This interface defines the methods required by all SIP user applications to receive and process JAIN SIP Events that are emitted by an object implementing the SipProvider interface.

SipProvider

This interface must be implemented by any Object representing a SIP Provider that interacts directly with a proprietary (stack vendor specific) implementation of a SIP stack.

SipStack

This interface defines the methods required to represent a proprietary SIP protocol stack, the implementation of which will be vendor specific.

SipURL

This interface represents a SIP URL.

URI

This interface represents a Universal Resource Identifier.

Class Summary SipFactory

The SipFactory is a singleton class by which applications can obtain a proprietary (Peer) JAIN SIP Object.

Exception Summary

ListeningPointUnavailableException

This Exception is thrown when an attempt is made to create a SipProvider with a ListeningPoint which is not owned by the SipStack or is being used byb another SipProvider

SipException

A SipException is thrown when a general JAIN SIP exception is encountered, and is used when no other subclass is appropriate.

This exception is thrown if the addSipListener method of a SipListenerAlreadyRegisteredException SipProvider is invoked to add a SipListener to the list of registered SipListeners, and the SipListener to be added is already a current registered SipListener. SipListenerNotRegisteredException

This exception is thrown if the removeSipListener method of a SipProvider is invoked to remove a SipListener from he list of registered SipListeners, and the SipListener to be removed is not currently a registered SipListener.

SipParseException

This exception is thrown by an implementation if it cannot parse any given value correctly.

SipPeerUnavailableException

The SipPeerUnavailableException indicates that the JAIN SIP Peer class (a particular implementation of JAIN SIP) could not be located in the classpath.

TransactionDoesNotExistException

This Exception is thrown when a user attempts to reference a transaction that does not exist

UnableToDeleteProviderException

This exception is thrown if the deleteProvider method of a SipStack is invoked to delete a SipProvider but the deletion is not allowed.

Package jain.protocol.ip.sip Description This package contains the main interfaces required to represent JAIN SIP protocol stacks, JAIN SIP applications, as well as the classes and exceptions needed to send and receive JAIN SIP messages. The implementation of the two stack vendor specific interfaces, namely SipStack and SipProvider will be vendor specific, however the naming of these proprietory implementations is mandated. The class name of the vendor specific implementations must be "SipImpl". For example a vendor implementation of the SipStack Interface must be called "SipStackImpl". Therefore once each vendor has implemented the JAIN SIP API specification they must has two proprietary classes called SipStackImpl.class and SipProviderImpl.class. The characteristics of the three main interfaces are listed below:

●

SipStack: This Interface defines the minimal management properties that enables the JAIN SIP API specification to operate independently. Therefore the TSipStack Object is a representation of the main management functionality of the SIP stack, as well as the central point for the creation of SipProviders. From within the SipStack Object it is possible for any application to get a list of SipProvider objects that are attached to the underlying SipStack by using the getSipProviders method with the SipStack Object. This method returns an array of SipProvider references of which a SipListener Object may register. Similiarly if the SipStack Object has no SipProviders attached to it, the SipListener may use the createSipProvider method to create a new SipProvider object.

●

SipProvider: This Interface defines the methods for adding SipListeners to, and removing SipListeners from a list of registered SipListeners held within the SipProvider. Other methods defined within the SipProvider provide the functionality for a SipListener to obtain a session with another SipListener based on a Call-Id. The SipProvider also defines the functionality to obtain CSeq numbers based on a specific Call-Id, that enables a SipListener to send requests to another SipListener to which a session has been initiated. In order for communication to take place between a local SipListener and a remote SipListener, the local SipListener must send a number of Messages to it's associated SipProvider.

●

SipListener: This Interface defines the methods required by all SipListeners to receive and process Messages that are emitted by a SipProvider. A remote SipProvider which receives Messages (which were sent by the local SipListener) from its underlying SIP stack, encapsulates them as Message and passes them to the remote SipListener. As mentioned above this occurs by Event passing, were the remote SipProvider invokes the processRequest , processResponse , processAck , processCancel , or processTimeout as appropriate and passes the relevant Event within the method to the remote SipListener. The same process occurs when the local SipProvider passes Message Events (received from the remote SipListener) to the local SipListener.

Note:

❍

A SipListener registers with a SipProvider to become an Event Listener of that SipProvider it registers with an object reference to itself. This value is stored by the SipProvider and is used to refer to its registered SipListeners.

❍

A SipListener may be registered with multiple SipProviders, which enables it to operate over a number of ListeningPoints.

The cardinality of the relationship between SipListeners and SipProviders is not restricted in any way. The restriction of this cardinality is dependent on a vendors specific implementation of the JAIN SIP API, were the necessary exceptions are thrown if the specificied cardinality is violated. However it is mandated that there may only be one TcapStack Object for each SIP stack, and only one SipProvider for each ListeningPoint of a SipStack. If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface AddressFactory public interface AddressFactory This interface provides factory methods to allow an application create address objects from a particular JAIN SIP implementation.

Method Summary NameAddress createNameAddress(java.lang.String displayName,

URI address) Creates a NameAddress based on given diaplay name and address NameAddress createNameAddress(URI address)

Creates a NameAddress based on given address SipURL createSipURL(java.net.InetAddress host)

Creates a SipURL based on given host SipURL createSipURL(java.lang.String host)

Creates a SipURL based on given host SipURL createSipURL(java.lang.String user,

java.net.InetAddress host) Creates a SipURL based on given user and host SipURL createSipURL(java.lang.String user, java.lang.String host)

Creates a SipURL based on given user and host URI createURI(java.lang.String scheme,

java.lang.String schemeData) Creates a URI based on given scheme and data

Method Detail createURI public URI createURI(java.lang.String scheme, java.lang.String schemeData) throws java.lang.IllegalArgumentException,

SipParseException Creates a URI based on given scheme and data Parameters: scheme - scheme schemeData - scheme data Throws: java.lang.IllegalArgumentException - if scheme or schemeData are null SipParseException - if scheme or schemeData is not accepted by implementation

createSipURL public SipURL createSipURL(java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Creates a SipURL based on given host Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null

createSipURL public SipURL createSipURL(java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Creates a SipURL based on given host Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

createSipURL public SipURL createSipURL(java.lang.String user,

java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Creates a SipURL based on given user and host Parameters: user - user host - host Throws: java.lang.IllegalArgumentException - if user or host is null SipParseException - if user or host is not accepted by implementation

createSipURL public SipURL createSipURL(java.lang.String user, java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Creates a SipURL based on given user and host Parameters: user - user host - host Throws: java.lang.IllegalArgumentException - if user or host is null SipParseException - if user or host is not accepted by implementation

createNameAddress public NameAddress createNameAddress(URI address) throws java.lang.IllegalArgumentException Creates a NameAddress based on given address Parameters: address - address URI Throws: java.lang.IllegalArgumentException - if address is null or not from same JAIN SIP implementation

createNameAddress public NameAddress createNameAddress(java.lang.String displayName, URI address) throws java.lang.IllegalArgumentException, SipParseException Creates a NameAddress based on given diaplay name and address Parameters: displayName - display name address - address URI Throws: java.lang.IllegalArgumentException - if displayName or address is null, or address is not from same JAIN SIP implementation SipParseException - if displayName is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface ListeningPoint public interface ListeningPoint extends java.lang.Cloneable, java.io.Serializable This interface represents a unique IP network listening point, and consists of host, port and transport Version: 0.7

Field Summary static int DEFAULT_PORT

Default port constant static java.lang.String TRANSPORT_TCP

TCP Transport constant static java.lang.String TRANSPORT_UDP

UDP Transport constant

Method Summary java.lang.Object clone()

Creates and returns a copy of ListeningPoint boolean equals(java.lang.Object obj)

Indicates whether some other Object is "equal to" this ListeningPoint (Note that obj must have the same Class as this ListeningPoint - this means that it must be from the same JAIN SIP implementation) java.lang.String getHost()

Gets host of ListeningPoint int getPort()

Gets port of ListeningPoint java.lang.String getTransport()

Gets transport of ListeningPoint

Field Detail TRANSPORT_UDP public static final java.lang.String TRANSPORT_UDP UDP Transport constant

TRANSPORT_TCP public static final java.lang.String TRANSPORT_TCP TCP Transport constant

DEFAULT_PORT public static final int DEFAULT_PORT Default port constant

Method Detail getHost public java.lang.String getHost() Gets host of ListeningPoint Returns: host of ListeningPoint

getPort public int getPort() Gets port of ListeningPoint Returns: port of ListeningPoint

getTransport public java.lang.String getTransport() Gets transport of ListeningPoint Returns: transport of ListeningPoint

equals public boolean equals(java.lang.Object obj) Indicates whether some other Object is "equal to" this ListeningPoint (Note that obj must have the same Class as this ListeningPoint - this means that it must be from the same JAIN SIP implementation) Overrides: equals in class java.lang.Object Parameters: obj - the Object with which to compare this ListeningPoint

clone public java.lang.Object clone() Creates and returns a copy of ListeningPoint If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface NameAddress public interface NameAddress extends java.lang.Cloneable, java.io.Serializable This interface represents a user's display name and address. NameAddress contains an optional display name for the user, which can be displayed to an end-user, and the URI (most likely a SipURL) that is the user's address. Version: 0.7 See Also: URI, SipURL, NameAddressHeader

Method Summary java.lang.Object clone()

Creates and returns a copy of NameAddress boolean equals(java.lang.Object obj)

Indicates whether some other Object is "equal to" this NameAddress (Note that obj must have the same Class as this NameAddress - this means that it must be from the same JAIN SIP implementation) URI getAddress()

Gets address of NameAddress java.lang.String getDisplayName()

Gets display name of NameAddress (Returns null id display name does not exist) boolean hasDisplayName()

Gets boolean value to indicate if NameAddress has display name void removeDisplayName()

Removes display name from NameAddress (if it exists) void setAddress(URI address)

Sets address of NameAddress void setDisplayName(java.lang.String displayName)

Sets display name of Header

java.lang.String toString()

Gets string representation of NameAddress

Method Detail getDisplayName public java.lang.String getDisplayName() Gets display name of NameAddress (Returns null id display name does not exist) Returns: display name of NameAddress

hasDisplayName public boolean hasDisplayName() Gets boolean value to indicate if NameAddress has display name Returns: boolean value to indicate if NameAddress has display name

removeDisplayName public void removeDisplayName() Removes display name from NameAddress (if it exists)

setDisplayName public void setDisplayName(java.lang.String displayName) throws java.lang.IllegalArgumentException, SipParseException Sets display name of Header Parameters: displayName - display name Throws:

java.lang.IllegalArgumentException - if displayName is null SipParseException - if displayName is not accepted by implementation

getAddress public URI getAddress() Gets address of NameAddress Returns: address of NameAddress

setAddress public void setAddress(URI address) throws java.lang.IllegalArgumentException Sets address of NameAddress Parameters: address - address Throws: java.lang.IllegalArgumentException - if address is null or not from same JAIN SIP implementation

toString public java.lang.String toString() Gets string representation of NameAddress Overrides: toString in class java.lang.Object Returns: string representation of NameAddress

equals public boolean equals(java.lang.Object obj) Indicates whether some other Object is "equal to" this NameAddress (Note that obj must have the

same Class as this NameAddress - this means that it must be from the same JAIN SIP implementation) Overrides: equals in class java.lang.Object Parameters: obj - the Object with which to compare this NameAddress

clone public java.lang.Object clone() Creates and returns a copy of NameAddress If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface Parameters All Known Subinterfaces: AcceptHeader, AuthorizationHeader, ContactHeader, ContentTypeHeader, EncryptionHeader, ParametersHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ResponseKeyHeader, SecurityHeader, SipURL, ViaHeader, WWWAuthenticateHeader public interface Parameters This interface represents a list of parameters. It is a super-interface of SipURL and ParametersHeader. Version: 0.7 See Also: SipURL, ParametersHeader

Method Summary java.lang.String getParameter(java.lang.String name)

Gets the value of specified parameter (Note - zero-length String indicates flag parameter) (Returns null if parameter does not exist) java.util.Iterator getParameters()

Gets Iterator of parameter names (Note - objects returned by Iterator are Strings) (Returns null if no parameters exist) boolean hasParameter(java.lang.String name)

Gets boolean value to indicate if Parameters has specified parameter boolean hasParameters()

Gets boolean value to indicate if Parameters has any parameters void removeParameter(java.lang.String name)

Removes specified parameter from Parameters (if it exists) void removeParameters()

Removes all parameters from Parameters (if any exist) void setParameter(java.lang.String name,

java.lang.String value) Sets value of parameter (Note - zero-length value String indicates flag parameter)

Method Detail getParameters public java.util.Iterator getParameters() Gets Iterator of parameter names (Note - objects returned by Iterator are Strings) (Returns null if no parameters exist) Returns: Iterator of parameter names

getParameter public java.lang.String getParameter(java.lang.String name) throws java.lang.IllegalArgumentException Gets the value of specified parameter (Note - zero-length String indicates flag parameter) (Returns null if parameter does not exist) Parameters: name - name of parameter to retrieve Returns: the value of specified parameter Throws: java.lang.IllegalArgumentException - if name is null

setParameter public void setParameter(java.lang.String name, java.lang.String value) throws java.lang.IllegalArgumentException, SipParseException Sets value of parameter (Note - zero-length value String indicates flag parameter) Parameters: name - name of parameter value - value of parameter Throws: java.lang.IllegalArgumentException - if name or value is null

SipParseException - if name or value is not accepted by implementation

hasParameters public boolean hasParameters() Gets boolean value to indicate if Parameters has any parameters Returns: boolean value to indicate if Parameters has any parameters

hasParameter public boolean hasParameter(java.lang.String name) throws java.lang.IllegalArgumentException Gets boolean value to indicate if Parameters has specified parameter Returns: boolean value to indicate if Parameters has specified parameter Throws: java.lang.IllegalArgumentException - if name is null

removeParameter public void removeParameter(java.lang.String name) throws java.lang.IllegalArgumentException Removes specified parameter from Parameters (if it exists) Parameters: name - name of parameter Throws: java.lang.IllegalArgumentException - if parameter is null

removeParameters public void removeParameters() Removes all parameters from Parameters (if any exist)

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface SipListener public interface SipListener extends java.util.EventListener This interface defines the methods required by all SIP user applications to receive and process JAIN SIP Events that are emitted by an object implementing the SipProvider interface. It must be noted that any object that implements the: ● SipListener Interface is referred to as SipListenerImpl. ● SipProvider Interface is referred to as SipProviderImpl. Version: 0.7 See Also: SipProvider

Method Summary void processRequest(java.lang.String serverTransactionId,

Request request) Processes a Request received on one of the SipListener's ListeningPoints. void processResponse(java.lang.String clientTransactionId,

Response response) Processes a Response received on one of the SipListener's ListeningPoints. void processTimeOut(java.lang.String transactionId,

boolean isServerTransaction) Processes the time out of a transaction specified by the transactionId.

Method Detail processRequest public void processRequest(java.lang.String serverTransactionId, Request request) Processes a Request received on one of the SipListener's ListeningPoints.

Parameters: serverTransactionId - the transaction ID of the server transaction associated with this Request request - the Resquest received

processResponse public void processResponse(java.lang.String clientTransactionId, Response response) Processes a Response received on one of the SipListener's ListeningPoints. Parameters: clientTransactionId - the transaction ID of the client transaction associated with this Response response - the Response received

processTimeOut public void processTimeOut(java.lang.String transactionId, boolean isServerTransaction) Processes the time out of a transaction specified by the transactionId. Parameters: transactionId - the transaction ID of the transaction that timed out. isServerTransaction - boolean value to indicate if transactionId corresponds to a server transaction If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface SipProvider public interface SipProvider This interface must be implemented by any Object representing a SIP Provider that interacts directly with a proprietary (stack vendor specific) implementation of a SIP stack. There is a one-to-one relationship between SipProviders and ListeningPoints. This interface defines the methods that will be used by any registered SIP User application (implementing the SipListener interface) to send SIP messages. It must be noted that any object that implements the: ● SipListener Interface is referred to as SipListenerImpl ● SipProvider Interface is referred to as SipProviderImpl ● SipStack Interface is referred to as SipStackImpl Version: 0.7 See Also: SipListener, SipStack

Method Summary void addSipListener(SipListener sipListener)

Adds SipListener to list of registered SipListeners of this SipProvider ListeningPoint getListeningPoint()

Returns ListeningPoint of this SipProvider CallIdHeader getNewCallIdHeader()

Returns new CallIdHeader (unique to SipProvider) CSeqHeader getNewCSeqHeader(CallIdHeader callIdHeader,

FromHeader fromHeader, ToHeader toHeader, java.lang.String method) Returns new CSeqHeader for call-leg represented by specified CallIdHeader, FromHeader and ToHeader SipStack getSipStack()

Returns SipStack that this SipProvider is attached to. Request getTransactionRequest(java.lang.String transactionId,

boolean isServerTransaction) Returns Request associated with specified transaction

Response getTransactionResponse(java.lang.String transactionId,

boolean isServerTransaction) Returns most recent Response associated with specified transaction (Returns null if there is no Response associated with specified transaction) void removeSipListener(SipListener sipListener)

Removes SipListener from list of registered SipListeners of this SipProvider java.lang.String sendAck(java.lang.String clientTransactionId)

Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction java.lang.String sendAck(java.lang.String clientTransactionId,

byte[] body, java.lang.String bodyType, java.lang.String bodySubType) Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction java.lang.String sendAck(java.lang.String clientTransactionId,

java.lang.String body, java.lang.String bodyType, java.lang.String bodySubType) Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction java.lang.String sendBye(java.lang.String transactionId,

boolean isServerTransaction) Sends automatically generated BYE Request based on specified client or server transaction (Note it is assumed that the specified transaction is the most recent one of the call-leg) java.lang.String sendCancel(java.lang.String clientTransactionId)

Sends automatically generated CANCEL Request to the recipient of the Request associated with specified client transaction java.lang.String sendRequest(Request request)

Sends specified Request and returns ID of implicitly created client transaction. void sendResponse(java.lang.String serverTransactionId,

int statusCode) Sends automatically generated Response for specified server transaction void sendResponse(java.lang.String serverTransactionId,

int statusCode, byte[] body, java.lang.String bodyType, java.lang.String bodySubType) Sends automatically generated Response for specified server transaction

void sendResponse(java.lang.String serverTransactionId,

int statusCode, java.lang.String body, java.lang.String bodyType, java.lang.String bodySubType) Sends automatically generated Response for specified server transaction void sendResponse(java.lang.String serverTransactionId,

Response response) Sends specified Response for specified server transaction

Method Detail addSipListener public void addSipListener(SipListener sipListener) throws java.lang.IllegalArgumentException, java.util.TooManyListenersException, SipListenerAlreadyRegisteredException Adds SipListener to list of registered SipListeners of this SipProvider Parameters: SipListener - SipListener to be added Throws: java.lang.IllegalArgumentException - if SipListener is null java.util.TooManyListenersException - if a limit has placed on number of registered SipListeners for this SipProvider, and this limit has been reached. SipListenerAlreadyRegisteredException - if SipListener is already registered with this SipProvider

removeSipListener public void removeSipListener(SipListener sipListener) throws java.lang.IllegalArgumentException, SipListenerNotRegisteredException Removes SipListener from list of registered SipListeners of this SipProvider Parameters: SipListener - SipListener to be removed from this SipProvider Throws: java.lang.IllegalArgumentException - if SipListener is null SipListenerNotRegisteredException - if SipListener is not registered with this SipProvider

getSipStack public SipStack getSipStack() Returns SipStack that this SipProvider is attached to. Returns: the attached SipStack.

getListeningPoint public ListeningPoint getListeningPoint() Returns ListeningPoint of this SipProvider Returns: ListeningPoint of this SipProvider

sendRequest public java.lang.String sendRequest(Request request) throws java.lang.IllegalArgumentException, SipException Sends specified Request and returns ID of implicitly created client transaction. Parameters: request - Request to send Returns: client transaction id (unique to underlying SipStack) Throws: java.lang.IllegalArgumentException - if request is null or not from same SIP implementation as SipProvider SipException - if implementation cannot send request for any other reason

sendAck public java.lang.String sendAck(java.lang.String clientTransactionId) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipException

Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction Parameters: clientTransactionId - client transaction id Returns: client transaction id (unique to the underlying SipStack) Throws: java.lang.IllegalArgumentException - if clientTransactionId is null TransactionDoesNotExistException - if clientTransactionId does not correspond to any client transaction SipException - if implementation cannot send ack for any other reason

sendAck public java.lang.String sendAck(java.lang.String clientTransactionId, java.lang.String body, java.lang.String bodyType, java.lang.String bodySubType) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipParseException, SipException Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction Parameters: clientTransactionId - client transaction id body - body of AckMessage bodyType - body type used to create ContentTypeHeader of AckMessage bodySubType - body sub-type used to create ContentTypeHeader of AckMessage Returns: client transaction id (unique to the underlying SipStack) Throws: java.lang.IllegalArgumentException - if clientTransactionId, body, bodyType or bodySubType are null TransactionDoesNotExistException - if clientTransactionId does not correspond to any client transaction SipParseException - if body, bodyType or bodySubType are not accepted by implementation SipException - if implementation cannot send ack for any other reason

sendAck public java.lang.String sendAck(java.lang.String clientTransactionId, byte[] body, java.lang.String bodyType, java.lang.String bodySubType) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipParseException, SipException Sends automatically generated ACK Request to the recipient of the INVITE Request associated with specified client transaction Parameters: clientTransactionId - client transaction id body - body of AckMessage bodyType - body type used to create ContentTypeHeader of AckMessage bodySubType - body sub-type used to create ContentTypeHeader of AckMessage Returns: client transaction id (unique to the underlying SipStack) Throws: java.lang.IllegalArgumentException - if clientTransactionId, body, bodyType or bodySubType are null TransactionDoesNotExistException - if clientTransactionId does not correspond to any client transaction SipParseException - if body, bodyType or bodySubType are not accepted by implementation SipException - if implementation cannot send ack for any other reason

sendCancel public java.lang.String sendCancel(java.lang.String clientTransactionId) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipException Sends automatically generated CANCEL Request to the recipient of the Request associated with specified client transaction Parameters: clientTransactionId - client transaction id Returns: client transaction id (unique to the underlying SipStack)

Throws: java.lang.IllegalArgumentException - if clientTransactionId is null TransactionDoesNotExistException - if clientTransactionId does not correspond to any client transaction SipException - if implementation cannot send cancel for any other reason

sendBye public java.lang.String sendBye(java.lang.String transactionId, boolean isServerTransaction) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipException Sends automatically generated BYE Request based on specified client or server transaction (Note it is assumed that the specified transaction is the most recent one of the call-leg) Parameters: transactionId - transaction id isServertransactionId - boolean value indicating if transactionId represents a server transaction Returns: client transaction id (unique to the underlying SipStack) Throws: java.lang.IllegalArgumentException - if transactionId is null TransactionDoesNotExistException - if transactionId does not correspond to client or server transaction SipException - if implementation cannot send bye for any other reason

sendResponse public void sendResponse(java.lang.String serverTransactionId, Response response) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipException Sends specified Response for specified server transaction Parameters: serverTransactionId - server transaction id response - the Response to send Throws:

java.lang.IllegalArgumentException - if serverTransactionId or response are null, or if response is not from same JAIN SIP implementation TransactionDoesNotExistException - if serverTransactionId does not correspond to any server transaction SipException - if implementation cannot send response for any other reason

sendResponse public void sendResponse(java.lang.String serverTransactionId, int statusCode) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipParseException, SipException Sends automatically generated Response for specified server transaction Parameters: serverTransactionId - server transaction id statusCode - the status code of Response Throws: java.lang.IllegalArgumentException - if serverTransactionId is null TransactionDoesNotExistException - if serverTransactionId does not correspond to any server transaction SipParseException - if statusCode is not accepted by implementation SipException - if implementation cannot send response for any other reason

sendResponse public void sendResponse(java.lang.String serverTransactionId, int statusCode, java.lang.String body, java.lang.String bodyType, java.lang.String bodySubType) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipParseException, SipException Sends automatically generated Response for specified server transaction Parameters: serverTransactionId - server transaction id

statusCode - the status code of Response body - body of Response bodyType - body type used to create ContentTypeHeader of Response bodySubType - body sub-type used to create ContentTypeHeader of Response Throws: java.lang.IllegalArgumentException - if serverTransactionId, body, bodyType or bodySubType are null TransactionDoesNotExistException - if serverTransactionId does not correspond to any server transaction SipParseException - if statusCode, body, bodyType or bodySubType are not accepted by implementation SipException - if implementation cannot send response for any other reason

sendResponse public void sendResponse(java.lang.String serverTransactionId, int statusCode, byte[] body, java.lang.String bodyType, java.lang.String bodySubType) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException, SipParseException, SipException Sends automatically generated Response for specified server transaction Parameters: serverTransactionId - server transaction id statusCode - the status code of Response body - body of Response bodyType - body type used to create ContentTypeHeader of Response bodySubType - body sub-type used to create ContentTypeHeader of Response Throws: java.lang.IllegalArgumentException - if serverTransactionId, body, bodyType or bodySubType are null TransactionDoesNotExistException - if serverTransactionId does not correspond to any server transaction SipParseException - if statusCode, body, bodyType or bodySubType are not accepted by implementation SipException - if implementation cannot send response for any other reason

getNewCallIdHeader public CallIdHeader getNewCallIdHeader() throws SipException Returns new CallIdHeader (unique to SipProvider) Returns: new CallIdHeader (unique to SipProvider) Throws: SipException - if SipProvider cannot generate a new CallIdHeader

getNewCSeqHeader public CSeqHeader getNewCSeqHeader(CallIdHeader callIdHeader, FromHeader fromHeader, ToHeader toHeader, java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException, SipException Returns new CSeqHeader for call-leg represented by specified CallIdHeader, FromHeader and ToHeader Parameters: callIdHeader - CallIdHeader of call-leg fromHeader - FromHeader of call-leg toHeader - ToHeader of call-leg Returns: new CSeqHeader for call-leg represented by specified CallIdHeader, FromHeader and ToHeader Throws: java.lang.IllegalArgumentException - if method is null, or if callIdHeader, fromHeader or toHeader are null or not from same JAIN SIP implementation SipParseException - if method is not accepted by implementation SipException - if SipProvider cannot create CSeqHeader for any other reason

getTransactionRequest public Request getTransactionRequest(java.lang.String transactionId, boolean isServerTransaction)

throws java.lang.IllegalArgumentException, TransactionDoesNotExistException Returns Request associated with specified transaction Parameters: transactionId - transaction id isServerTransaction - boolean value to indicate if transactionId represents a server transaction Returns: Request associated with specified transaction Throws: java.lang.IllegalArgumentException - if transactionId is null TransactionDoesNotExistException - if transactionId does not correspond to a transaction

getTransactionResponse public Response getTransactionResponse(java.lang.String transactionId, boolean isServerTransaction) throws java.lang.IllegalArgumentException, TransactionDoesNotExistException Returns most recent Response associated with specified transaction (Returns null if there is no Response associated with specified transaction) Parameters: transactionId - transaction id isServerTransaction - boolean value to indicate if transactionId represents a server transaction Returns: the Request associated with server transaction Throws: java.lang.IllegalArgumentException - if transactionId is null TransactionDoesNotExistException - if transactionId does not correspond to a transaction If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface SipStack public interface SipStack This interface defines the methods required to represent a proprietary SIP protocol stack, the implementation of which will be vendor specific. Each vendor's protocol stack will have an object that implements this interface to control the creation/deletion of proprietary SipProviders. It must be noted that under the JAIN Naming Convention the lower-level package structure and classname of a proprietary implementation of the jain.protocol.ip.sip.SipStack interface must be jain.protocol.ip.sip.SipStackImpl. Under the JAIN naming convention, the upper-level package structure (pathname) can be used to differentiate between proprietary implementations from different IP Vendors. The pathname used by each IP Vendor must be the domain name assigned to the Vendor in reverse order, e.g. Sun Microsystem's would be 'com.sun' It follows that a proprietary implementation of a SipStack will be located at: pathname.jain.protocol.ip.sip.SipStackImpl Where: pathname = reverse domain name, e.g. com.sun' The resulting Peer JAIN IP Object would be located at: com.sun.jain.protocol.ip.sip.SipStackImpl An application must create a SipStackImpl by invoking the SipFactory.createSipStack() method. The PathName of the vendor specific implementation of which you want to instantiate can be set before calling this method or the default or current pathname may be used. For applications that require some means to identify multiple stacks setStackName() can be used. An application can choose to supply any identifier to this method. Version: 0.7 See Also: SipFactory, SipProvider

Method Summary SipProvider createSipProvider(ListeningPoint listeningPoint)

Creates a new Peer (vendor specific) SipProvider that is attached to this SipStack on a specified ListeningPoint and returns a reference to it. void deleteSipProvider(SipProvider sipProvider)

Deletes the specified Peer JAIN SIP Provider attached to this SipStack.

java.util.Iterator getListeningPoints()

Returns an Iterator of ListeningPoints available to this stack (Returns null if no ListeningPoints exist) java.util.Iterator getSipProviders()

Returns an Iterator of existing Peer JAIN SIP Providers that have been created by this SipStackImpl. java.lang.String getStackName()

Gets the name of this SipStack instance. void setStackName(java.lang.String stackName)

Sets the name of this SipStack instance.

Method Detail getListeningPoints public java.util.Iterator getListeningPoints() Returns an Iterator of ListeningPoints available to this stack (Returns null if no ListeningPoints exist) Returns: an Iterator of ListeningPoints available to this stack

createSipProvider public SipProvider createSipProvider(ListeningPoint listeningPoint) throws java.lang.IllegalArgumentException, ListeningPointUnavailableException Creates a new Peer (vendor specific) SipProvider that is attached to this SipStack on a specified ListeningPoint and returns a reference to it. Note to developers: The implementation of this method should add the newly created SipProvider to the providerList once the SipProvider has been successfully created. Parameters: listeningPoint - the ListeningPoint the Provider is to be attached to Returns: Peer JAIN Sip Provider attached to this SipStack on specified ListeningPoint. Throws: IPPeerUnavailableException - thrown if the Peer class could not be found ListeningPointUnavailableException - thrown if the ListeningPoint specified is not owned by

this SipStack, or if another Provider is already using the ListeningPoint java.lang.IllegalArgumentException - if listeningPoint is null

deleteSipProvider public void deleteSipProvider(SipProvider sipProvider) throws UnableToDeleteProviderException, java.lang.IllegalArgumentException Deletes the specified Peer JAIN SIP Provider attached to this SipStack. Note to developers: The implementation of this method should remove the specified Peer JAIN SIP Provider from the providerList. Parameters: providerToBeDeleted - the Peer JAIN SIP Provider to be deleted from this SipStack. Throws: UnableToDeleteProviderException - thrown if the specified Peer JAIN SIP Provider cannot be deleted. This may be because the Peer JAIN SIP Provider has already been deleted, or because the Peer JAIN SIP Provider is currently in use. java.lang.IllegalArgumentException - if providerToBeDeleted is null

getSipProviders public java.util.Iterator getSipProviders() Returns an Iterator of existing Peer JAIN SIP Providers that have been created by this SipStackImpl. All of the Peer JAIN SIP Providers of this SipStack will be proprietary objects belonging to the same stack vendor. (Returns null if no SipProviders exist) Returns: an Iterator containing all existing Peer JAIN SIP Providers created by this SipStack.

getStackName public java.lang.String getStackName() Gets the name of this SipStack instance. Returns: a string describing the stack instance

setStackName public void setStackName(java.lang.String stackName) throws java.lang.IllegalArgumentException Sets the name of this SipStack instance. This name should be unique to this instance of a vendor's implementation and optionally include a means to identify what listening points the stack owns. Parameters: stackName/var> - the stack name. Throws: java.lang.IllegalArgumentException - if stackName is null or zero-length If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface SipURL public interface SipURL extends URI, Parameters This interface represents a SIP URL. SipURLs are used to indicate the originator (FromHeader), current destination (RequestURI) and final recipient (ToHeader) of a SIP Request, and to specify redirection addresses (ContactHeader). A SipURL can also be embedded in web pages or other hyperlinks to indicate that a particular user or service can be called via SIP. When used as a hyperlink, the SipURL indicates the use of the INVITE method. The SipURL scheme is defined to allow setting headers and the message-body. This corresponds to the use of mailto: URLs. It makes it possible, for example, to specify the subject, urgency or media types of calls initiated through a web page or as part of an email message. The components of the SipURL have the following meanings: ● UserName: If the host is an Internet telephony gateway, the UserName may also encode a telephone number. Thus, a URL parameter, UserType, is added to distinguish telephone numbers from user names. The phone identifier is to be used when connecting to a telephony gateway. Even without this parameter, recipients of SipURLs may interpret the UserName part as a phone number if local restrictions on the name space for user name allow it. ● UserPassword: The use of passwords in the userinfo is not recommended, because the passing of authentication information in clear text (such as URIs) has proven to be a security risk in almost every case where it has been used. ● Host: The mailto: URL and RFC 822 email addresses require that numeric host addresses ("host numbers") are enclosed in square brackets (presumably, since host names might be numeric), while host numbers without brackets are used for all other URLs. The SipURL requires the latter form, without brackets. ● Port: The port number to send a Request to. ● URL parameters: SipURLs can define specific parameters of the Request. The Transport parameter determines the transport mechanism (UDP or TCP). UDP is to be assumed when no explicit transport parameter is included. The MAddr parameter provides the server address to be contacted for this user, overriding the address supplied in the host field. This address is typically a multicast address, but could also be the address of a backup server. The TTL parameter determines the time-to-live value of the UDP multicast packet and must only be used if maddr is a multicast address and the transport protocol is UDP. The UserType parameter was described above. The Transport, MAddr, and TTL parameters must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present. ● Headers: Headers of the SIP Request can be defined within a SIP URL. The special header name "body" indicates that the associated header value is the message-body of the SIP INVITE Request. Headers must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present. ● Method: The method of the SIP Request can be specified with the Method parameter. This parameter

must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present. Within a SIP Message, SipURLs are used to indicate the source and intended destination of a RequestMessage, redirection addresses and the current destination of a RequestMessage. Normally all these Headers will contain SipURLs. SipURLs are case-insensitive. All SipURL parameters are included when comparing for equality. Version: 0.7 See Also: Request, FromHeader, ToHeader

Field Summary static java.lang.String USER_TYPE_IP

IP User Type constant static java.lang.String USER_TYPE_PHONE

Phone User Type constant

Method Summary java.lang.String getHeader(java.lang.String name)

Gets the value of specified header (Returns null if header does not exist) java.util.Iterator getHeaders()

Gets Iterator of header names (Note - objects returned by Iterator are Strings) (Returns null if no headers exist) java.lang.String getHost()

Gets host of SipURL java.lang.String getIsdnSubAddress()

Gets ISDN subaddress of SipURL (Returns null if ISDN subaddress does not exist) java.lang.String getMAddr()

Gets MAddr of SipURL (Returns null if MAddr does not exist) java.lang.String getMethod()

Gets method of SipURL (Returns null if method does not exist) int getPort()

Gets port of SipURL (Returns negative int if port does not exist)

java.lang.String getPostDial()

Gets post dial of SipURL (Returns null if post dial does not exist) java.lang.String getTransport()

Gets transport of SipURL (Returns null if transport does not exist) int getTTL()

Gets TTL of SipURL (Returns negative int if TTL does not exist) java.lang.String getUserName()

Gets user name of SipURL (Returns null if user name does not exist) java.lang.String getUserPassword()

Gets user password of SipURL (Returns null if user pasword does not exist) java.lang.String getUserType()

Gets user type of SipURL (Returns null if user type does not exist) boolean hasHeader(java.lang.String name)

Gets boolean value to indicate if SipUrl has specified header boolean hasHeaders()

Gets boolean value to indicate if SipURL has any headers boolean hasIsdnSubAddress()

Gets boolean value to indicate if SipURL has ISDN subaddress boolean hasMAddr()

Gets boolean value to indicate if SipURL has MAddr boolean hasMethod()

Gets boolean value to indicate if SipURL has method boolean hasPort()

Gets boolean value to indicate if SipURL has port boolean hasPostDial()

Gets boolean value to indicate if SipURL has post dial boolean hasTransport()

Gets boolean value to indicate if SipURL has transport boolean hasTTL()

Gets boolean value to indicate if SipURL has TTL boolean hasUserName()

Gets boolean value to indicate if SipURL has user name boolean hasUserPassword()

Gets boolean value to indicate if SipURL has user password

boolean hasUserType()

Gets boolean value to indicate if SipURL has user type boolean isGlobal()

Returns boolean value to indicate if the SipURL has a global phone user void removeHeader(java.lang.String name)

Removes specified header from SipURL (if it exists) void removeHeaders()

Removes all parameters from Parameters (if any exist) void removeIsdnSubAddress()

Removes ISDN subaddress from SipURL (if it exists) void removeMAddr()

Removes MAddr from SipURL (if it exists) void removeMethod()

Removes method from SipURL (if it exists) void removePort()

Removes port from SipURL (if it exists) void removePostDial()

Removes post dial from SipURL (if it exists) void removeTransport()

Removes transport from SipURL (if it exists) void removeTTL()

Removes TTL from SipURL (if it exists) void removeUserName()

Removes user name from SipURL (if it exists) void removeUserPassword()

Removes user password from SipURL (if it exists) void removeUserType()

Removes user type from SipURL (if it exists) void setGlobal(boolean global)

Sets phone user of SipURL to be global or local void setHeader(java.lang.String name,

java.lang.String value) Sets value of header

void setHost(java.net.InetAddress host)

Sets host of SipURL void setHost(java.lang.String host)

Sets host of SipURL void setIsdnSubAddress(java.lang.String isdnSubAddress)

Sets ISDN subaddress of SipURL void setMAddr(java.net.InetAddress mAddr)

Sets MAddr of SipURL void setMAddr(java.lang.String mAddr)

Sets MAddr of SipURL void setMethod(java.lang.String method)

Sets method of SipURL void setPort(int port)

Sets port of SipURL void setPostDial(java.lang.String postDial)

Sets post dial of SipURL void setTransport(java.lang.String transport)

Sets transport of SipURL void setTTL(int ttl)

Sets TTL of SipURL void setUserName(java.lang.String userName)

Sets user name of SipURL void setUserPassword(java.lang.String userPassword)

Sets user password of SipURL void setUserType(java.lang.String userType)

Sets user type of SipURL

Methods inherited from interface jain.protocol.ip.sip.URI clone, equals, getScheme, getSchemeData, setScheme, setSchemeData, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters

getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail USER_TYPE_IP public static final java.lang.String USER_TYPE_IP IP User Type constant

USER_TYPE_PHONE public static final java.lang.String USER_TYPE_PHONE Phone User Type constant

Method Detail getIsdnSubAddress public java.lang.String getIsdnSubAddress() Gets ISDN subaddress of SipURL (Returns null if ISDN subaddress does not exist) Returns: ISDN subaddress of SipURL

hasIsdnSubAddress public boolean hasIsdnSubAddress() Gets boolean value to indicate if SipURL has ISDN subaddress Returns: boolean value to indicate if SipURL has ISDN subaddress

removeIsdnSubAddress public void removeIsdnSubAddress() Removes ISDN subaddress from SipURL (if it exists)

getPostDial public java.lang.String getPostDial() Gets post dial of SipURL (Returns null if post dial does not exist) Returns: post dial of SipURL

hasPostDial public boolean hasPostDial() Gets boolean value to indicate if SipURL has post dial Returns: boolean value to indicate if SipURL has post dial

removePostDial public void removePostDial() Removes post dial from SipURL (if it exists)

getUserName public java.lang.String getUserName() Gets user name of SipURL (Returns null if user name does not exist) Returns: user name of SipURL

hasUserName public boolean hasUserName() Gets boolean value to indicate if SipURL has user name Returns: boolean value to indicate if SipURL has user name

removeUserName public void removeUserName() Removes user name from SipURL (if it exists)

setUserName public void setUserName(java.lang.String userName) throws java.lang.IllegalArgumentException, SipParseException Sets user name of SipURL Parameters: userName - user name Throws: java.lang.IllegalArgumentException - if userName is null SipParseException - if userName is not accepted by implementation

getUserPassword public java.lang.String getUserPassword() Gets user password of SipURL (Returns null if user pasword does not exist) Returns: user password of SipURL

hasUserPassword public boolean hasUserPassword() Gets boolean value to indicate if SipURL has user password Returns: boolean value to indicate if SipURL has user password

removeUserPassword public void removeUserPassword() Removes user password from SipURL (if it exists)

setUserPassword public void setUserPassword(java.lang.String userPassword) throws java.lang.IllegalArgumentException, SipException, SipParseException Sets user password of SipURL Parameters: userPassword - user password Throws: java.lang.IllegalArgumentException - if userPassword is null SipException - if user name does not exist SipParseException - if userPassword is not accepted by implementation

getHost public java.lang.String getHost() Gets host of SipURL Returns: host of SipURL

setHost public void setHost(java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Sets host of SipURL Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

setHost public void setHost(java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Sets host of SipURL Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

getPort public int getPort() Gets port of SipURL (Returns negative int if port does not exist) Returns: port of SipURL

hasPort public boolean hasPort()

Gets boolean value to indicate if SipURL has port Returns: boolean value to indicate if SipURL has port

removePort public void removePort() Removes port from SipURL (if it exists)

setPort public void setPort(int port) throws SipParseException Sets port of SipURL Parameters: port - port Throws: SipParseException - if port is not accepted by implementation

getTTL public int getTTL() Gets TTL of SipURL (Returns negative int if TTL does not exist) Returns: TTL of SipURL

hasTTL public boolean hasTTL() Gets boolean value to indicate if SipURL has TTL Returns: boolean value to indicate if SipURL has TTL

removeTTL public void removeTTL() Removes TTL from SipURL (if it exists)

setTTL public void setTTL(int ttl) throws SipParseException Sets TTL of SipURL Parameters: ttl - TTL Throws: SipParseException - if ttl is not accepted by implementation

getTransport public java.lang.String getTransport() Gets transport of SipURL (Returns null if transport does not exist) Returns: transport of SipURL

hasTransport public boolean hasTransport() Gets boolean value to indicate if SipURL has transport Returns: boolean value to indicate if SipURL has transport

removeTransport public void removeTransport() Removes transport from SipURL (if it exists)

setTransport public void setTransport(java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Sets transport of SipURL Parameters: transport - transport Throws: java.lang.IllegalArgumentException - if transport is null SipParseException - if transport is not accepted by implementation

getUserType public java.lang.String getUserType() Gets user type of SipURL (Returns null if user type does not exist) Returns: user type of SipURL

hasUserType public boolean hasUserType() Gets boolean value to indicate if SipURL has user type Returns: boolean value to indicate if SipURL has user type

removeUserType public void removeUserType() Removes user type from SipURL (if it exists)

setUserType public void setUserType(java.lang.String userType) throws java.lang.IllegalArgumentException, SipParseException Sets user type of SipURL Parameters: userType - user type Throws: java.lang.IllegalArgumentException - if userType is null SipParseException - if userType is not accepted by implementation

getMethod public java.lang.String getMethod() Gets method of SipURL (Returns null if method does not exist) Returns: method of SipURL

hasMethod public boolean hasMethod() Gets boolean value to indicate if SipURL has method Returns: boolean value to indicate if SipURL has method

removeMethod public void removeMethod() Removes method from SipURL (if it exists)

setMethod public void setMethod(java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException Sets method of SipURL Parameters: method - method Throws: java.lang.IllegalArgumentException - if method is null SipParseException - if method is not accepted by implementation

setIsdnSubAddress public void setIsdnSubAddress(java.lang.String isdnSubAddress) throws java.lang.IllegalArgumentException, SipException, SipParseException Sets ISDN subaddress of SipURL Parameters: isdnSubAddress - ISDN subaddress Throws: java.lang.IllegalArgumentException - if isdnSubAddress is null SipException - if user type is not USER_TYPE_PHONE SipParseException - if isdnSubAddress is not accepted by implementation

setPostDial public void setPostDial(java.lang.String postDial) throws java.lang.IllegalArgumentException, SipException, SipParseException Sets post dial of SipURL Parameters: postDial - post dial

Throws: java.lang.IllegalArgumentException - if postDial is null SipException - if user type is not USER_TYPE_PHONE SipParseException - if postDial is not accepted by implementation

getMAddr public java.lang.String getMAddr() Gets MAddr of SipURL (Returns null if MAddr does not exist) Returns: MAddr of SipURL

hasMAddr public boolean hasMAddr() Gets boolean value to indicate if SipURL has MAddr Returns: boolean value to indicate if SipURL has MAddr

removeMAddr public void removeMAddr() Removes MAddr from SipURL (if it exists)

setMAddr public void setMAddr(java.lang.String mAddr) throws java.lang.IllegalArgumentException, SipParseException Sets MAddr of SipURL Parameters: mAddr - MAddr Throws: java.lang.IllegalArgumentException - if mAddr is null

SipParseException - if mAddr is not accepted by implementation

setMAddr public void setMAddr(java.net.InetAddress mAddr) throws java.lang.IllegalArgumentException, SipParseException Sets MAddr of SipURL Parameters: mAddr - MAddr Throws: java.lang.IllegalArgumentException - if mAddr is null SipParseException - if mAddr is not accepted by implementation

isGlobal public boolean isGlobal() throws SipException Returns boolean value to indicate if the SipURL has a global phone user Returns: boolean value to indicate if the SipURL has a global phone user Throws: SipException - if user type is not USER_TYPE_PHONE

setGlobal public void setGlobal(boolean global) throws SipException, SipParseException Sets phone user of SipURL to be global or local Parameters: global - boolean value indicating if phone user should be global Throws: SipException - if user type is not USER_TYPE_PHONE

getHeaders public java.util.Iterator getHeaders() Gets Iterator of header names (Note - objects returned by Iterator are Strings) (Returns null if no headers exist) Returns: Iterator of header names

getHeader public java.lang.String getHeader(java.lang.String name) throws java.lang.IllegalArgumentException Gets the value of specified header (Returns null if header does not exist) Parameters: name - name of header to retrieve Returns: the value of specified header Throws: java.lang.IllegalArgumentException - if header is null

setHeader public void setHeader(java.lang.String name, java.lang.String value) throws java.lang.IllegalArgumentException, SipParseException Sets value of header Parameters: name - name of header value - value of header Throws: java.lang.IllegalArgumentException - if name or value is null SipParseException - if name or value is not accepted by implementation

hasHeaders public boolean hasHeaders() Gets boolean value to indicate if SipURL has any headers Returns: boolean value to indicate if SipURL has any headers

hasHeader public boolean hasHeader(java.lang.String name) throws java.lang.IllegalArgumentException Gets boolean value to indicate if SipUrl has specified header Returns: boolean value to indicate if SipUrl has specified header Throws: java.lang.IllegalArgumentException - if name is null

removeHeader public void removeHeader(java.lang.String name) throws java.lang.IllegalArgumentException Removes specified header from SipURL (if it exists) Parameters: name - name of header Throws: java.lang.IllegalArgumentException - if name is null

removeHeaders public void removeHeaders() Removes all parameters from Parameters (if any exist) If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Interface URI All Known Subinterfaces: SipURL public interface URI extends java.lang.Cloneable, java.io.Serializable This interface represents a Universal Resource Identifier. A URI contains a scheme and the scheme data which, in combination, provide a means to locate a resource. This API defines one such scheme - "sip", and has a SipURL class to represent this type of URI. Version: 0.7 See Also: SipURL

Method Summary java.lang.Object clone()

Creates and returns a copy of URI boolean equals(java.lang.Object obj)

Indicates whether some other Object is "equal to" this URI (Note that obj must have the same Class as this URI - this means that it must be from the same JAIN SIP implementation) java.lang.String getScheme()

Gets scheme of URI java.lang.String getSchemeData()

Gets scheme data of URI void setScheme(java.lang.String scheme)

Sets scheme of URI void setSchemeData(java.lang.String schemeData)

Sets scheme data of URI java.lang.String toString()

Gets string representation of URI

Method Detail setSchemeData public void setSchemeData(java.lang.String schemeData) throws java.lang.IllegalArgumentException, SipParseException Sets scheme data of URI Parameters: schemeData - scheme data Throws: java.lang.IllegalArgumentException - if schemeData is null SipParseException - if schemeData is not accepted by implementation

toString public java.lang.String toString() Gets string representation of URI Overrides: toString in class java.lang.Object Returns: string representation of URI

getSchemeData public java.lang.String getSchemeData() Gets scheme data of URI Returns: scheme data of URI

setScheme public void setScheme(java.lang.String scheme) throws java.lang.IllegalArgumentException,

SipParseException Sets scheme of URI Parameters: scheme - scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

getScheme public java.lang.String getScheme() Gets scheme of URI Returns: scheme of URI

equals public boolean equals(java.lang.Object obj) Indicates whether some other Object is "equal to" this URI (Note that obj must have the same Class as this URI - this means that it must be from the same JAIN SIP implementation) Overrides: equals in class java.lang.Object Parameters: obj - the Object with which to compare this URI

clone public java.lang.Object clone() Creates and returns a copy of URI If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipFactory java.lang.Object | +--jain.protocol.ip.sip.SipFactory public class SipFactory extends java.lang.Object The SipFactory is a singleton class by which applications can obtain a proprietary (Peer) JAIN SIP Object. The term 'peer' is Java nomenclature for "a particular platform-specific implementation of a Java interface or API". This term has the same meaning for the JAIN SIP API specification. A Peer JAIN SIP Object can be obtained from the SipFactory by invoking the appropriate create method e.g. to create a peer SipStack, invoke the createSipStack() method, or Note that the SipFactory utilises a naming convention defined for the JAIN SIP API to identify the location of proprietary JAIN SIP Objects. Under this convention the lower-level package structure and classname of a Peer JAIN SIP Object is mandated by a convention defined within the JAIN SIP API. For example: the lower-level package structure and classname of a proprietary implementation of the jain.protocol.ip.sip.SipStack interface must be jain.protocol.ip.sip.SipStackImpl. Under the JAIN naming convention, the upper-level package structure (pathname) can be used to differentiate between proprietary implementations from different SIP Vendors. The pathname used by each SIP Vendor must be the domain name assigned to the Vendor in reverse order, e.g. Sun Microsystem's would be 'com.sun' It follows that a proprietary implementation of a JAIN SIP Object can be located at: 'pathname'.'lower-level package structure and classname' Where: pathname = reverse domain name, e.g. com.sun' lower-level package structure and classname = mandated naming convention for the JAIN SIP Object in question e.g. jain.protocol.ip.sip.SipStackImpl is the mandated naming convention for jain.protocol.ip.sip.SipStack. The resulting Peer JAIN SIP Object would be located at: com.sun.jain.protocol.ip.sip.SipStackImpl Because the space of domain names is managed, this scheme ensures that collisions between two different vendor's implementations will not happen. For example: a different Vendor with a domain name

'foo.com' would have their Peer SipStack Object located at com.foo.jain.protocol.ip.sip.SipStackImpl. This is a similar concept to the JAVA conventions used for managing package names. The pathname is defaulted to 'com.dynamicsoft.ri' for the reference implementation but may be set using the setPathName() method. This allows a JAIN SIP application to switch between different Vendor implementations, as well as providing the capability to use the default or current pathname. Not though, that you cannot mix different vendor's JAIN SIP objects. The SipFactory is a Singleton class. This means that there will only be one instance of the class with a global point of access to it. The single instance of the SipFactory can be obtained using the getInstance() method. In this way, the SipFactory can acts a single point for obtaining JAIN SIP Objects. Version: 0.7

Method Summary AddressFactory createAddressFactory()

HeaderFactory createHeaderFactory()

MessageFactory createMessageFactory()

SipStack createSipStack()

static SipFactory getInstance()

Returns an instance of a SipFactory. java.lang.String getPathName()

Returns the current Pathname. void setPathName(java.lang.String pathName)

Sets the Pathname that identifies the location of a particular Vendor's implementation of the JAIN SIP Objects.

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance public static SipFactory getInstance() Returns an instance of a SipFactory. This is a singleton type class so this method is the global access point for the SipFactory. Returns: the single instance of this singleton SipFactory

setPathName public void setPathName(java.lang.String pathName) Sets the Pathname that identifies the location of a particular Vendor's implementation of the JAIN SIP Objects. The pathname must be the domain name assigned to the Vendor providing the implementation in reverse order. Parameters: pathName - the reverse domain name of the Vendor. e.g. Sun Microsystem's would be 'com.sun'

getPathName public java.lang.String getPathName() Returns the current Pathname. The pathname identifies the location of a particular Vendor's implementation of the JAIN SIP Objects. The pathname will always be the domain name assigned to the Vendor providing the implementation in reverse order. Returns: the pathname

createSipStack public SipStack createSipStack() throws SipPeerUnavailableException

createAddressFactory public AddressFactory createAddressFactory() throws SipPeerUnavailableException

createHeaderFactory public HeaderFactory createHeaderFactory() throws SipPeerUnavailableException

createMessageFactory public MessageFactory createMessageFactory() throws SipPeerUnavailableException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class ListeningPointUnavailableException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.ListeningPointUnavailableException public final class ListeningPointUnavailableException extends SipException This Exception is thrown when an attempt is made to create a SipProvider with a ListeningPoint which is not owned by the SipStack or is being used byb another SipProvider Version: 0.7 See Also: Serialized Form

Constructor Summary ListeningPointUnavailableException() Constructs a new ListeningPointUnavailableException ListeningPointUnavailableException(java.lang.String msg) Constructs a new ListeningPointUnavailableException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ListeningPointUnavailableException public ListeningPointUnavailableException(java.lang.String msg) Constructs a new ListeningPointUnavailableException with the specified detail message. Parameters: msg - the detail message

ListeningPointUnavailableException public ListeningPointUnavailableException() Constructs a new ListeningPointUnavailableException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException Direct Known Subclasses: ListeningPointUnavailableException, SipListenerAlreadyRegisteredException, SipListenerNotRegisteredException, SipParseException, SipPeerUnavailableException, TransactionDoesNotExistException, UnableToDeleteProviderException public class SipException extends java.lang.Exception A SipException is thrown when a general JAIN SIP exception is encountered, and is used when no other subclass is appropriate. Version: 0.7 See Also: Serialized Form

Constructor Summary SipException() Constructs a new SipException SipException(java.lang.String msg) Constructs a new SipException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail SipException public SipException(java.lang.String msg) Constructs a new SipException with the specified detail message. Parameters: msg - the message detail of this Exception.

SipException public SipException() Constructs a new SipException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipListenerAlreadyRegisteredException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.SipListenerAlreadyRegisteredException public class SipListenerAlreadyRegisteredException extends SipException This exception is thrown if the addSipListener method of a SipProvider is invoked to add a SipListener to the list of registered SipListeners, and the SipListener to be added is already a current registered SipListener. Version: 0.7 See Also: Serialized Form

Constructor Summary SipListenerAlreadyRegisteredException() Constructs a new SipListenerAlreadyRegisteredException SipListenerAlreadyRegisteredException(java.lang.String msg) Constructs a new SipListenerAlreadyRegisteredException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SipListenerAlreadyRegisteredException public SipListenerAlreadyRegisteredException(java.lang.String msg) Constructs a new SipListenerAlreadyRegisteredException with the specified detail message. Parameters: msg - the detail message

SipListenerAlreadyRegisteredException public SipListenerAlreadyRegisteredException() Constructs a new SipListenerAlreadyRegisteredException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipListenerNotRegisteredException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.SipListenerNotRegisteredException public class SipListenerNotRegisteredException extends SipException This exception is thrown if the removeSipListener method of a SipProvider is invoked to remove a SipListener from he list of registered SipListeners, and the SipListener to be removed is not currently a registered SipListener. Version: 0.7 See Also: Serialized Form

Constructor Summary SipListenerNotRegisteredException() Constructs a new SipListenerNotRegisteredException SipListenerNotRegisteredException(java.lang.String msg) Constructs a new SipListenerNotRegisteredException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SipListenerNotRegisteredException public SipListenerNotRegisteredException(java.lang.String msg) Constructs a new SipListenerNotRegisteredException with the specified detail message. Parameters: msg - the detail message

SipListenerNotRegisteredException public SipListenerNotRegisteredException() Constructs a new SipListenerNotRegisteredException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipParseException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.SipParseException Direct Known Subclasses: HeaderParseException public class SipParseException extends SipException This exception is thrown by an implementation if it cannot parse any given value correctly. The value that is unable to be parsed correctly can be accessed using the getUnparsable method. Version: 0.7 See Also: Serialized Form

Constructor Summary SipParseException(java.lang.String unparsable) Constructs new SipParseException based on specified unparsable value SipParseException(java.lang.String message, java.lang.String unparsable) Constructs new SipParseException based on specified unparsable value and a message

Method Summary java.lang.String getUnparsable()

Gets unparsable value of SipParseException

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail SipParseException public SipParseException(java.lang.String message, java.lang.String unparsable) Constructs new SipParseException based on specified unparsable value and a message Parameters: msg - message of this SipParseException. unspasable - unparsable value to base SipParseException on

SipParseException public SipParseException(java.lang.String unparsable) Constructs new SipParseException based on specified unparsable value Parameters: unspasable - unparsable value to base SipParseException on

Method Detail getUnparsable public java.lang.String getUnparsable() Gets unparsable value of SipParseException Returns:

unparsable value of SipParseException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class SipPeerUnavailableException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.SipPeerUnavailableException public class SipPeerUnavailableException extends SipException The SipPeerUnavailableException indicates that the JAIN SIP Peer class (a particular implementation of JAIN SIP) could not be located in the classpath. Version: 0.7 See Also: Serialized Form

Constructor Summary SipPeerUnavailableException() Constructs a new JAIN SIP Peer Unavailable Exception. SipPeerUnavailableException(java.lang.String msg) Constructs a new JAIN SIP Peer Unavailable Exception with the specified message detail.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail SipPeerUnavailableException public SipPeerUnavailableException(java.lang.String msg) Constructs a new JAIN SIP Peer Unavailable Exception with the specified message detail. Parameters: msg - the message detail of this Exception.

SipPeerUnavailableException public SipPeerUnavailableException() Constructs a new JAIN SIP Peer Unavailable Exception. If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class TransactionDoesNotExistException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.TransactionDoesNotExistException public class TransactionDoesNotExistException extends SipException This Exception is thrown when a user attempts to reference a transaction that does not exist Version: 0.7 See Also: Serialized Form

Constructor Summary TransactionDoesNotExistException() Constructs a new TransactionDoesNotExistException TransactionDoesNotExistException(java.lang.String msg) Constructs a new TransactionDoesNotExistException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionDoesNotExistException public TransactionDoesNotExistException(java.lang.String msg) Constructs a new TransactionDoesNotExistException with the specified detail message. Parameters: msg - the detail message

TransactionDoesNotExistException public TransactionDoesNotExistException() Constructs a new TransactionDoesNotExistException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip

Class UnableToDeleteProviderException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.UnableToDeleteProviderException public class UnableToDeleteProviderException extends SipException This exception is thrown if the deleteProvider method of a SipStack is invoked to delete a SipProvider but the deletion is not allowed. This may be because the SipProvider has already been deleted, or because the SipProvider is in use. Version: 0.7 See Also: Serialized Form

Constructor Summary UnableToDeleteProviderException() Constructs a new UnableToDeleteProviderException UnableToDeleteProviderException(java.lang.String msg) Constructs a new UnableToDeleteProviderException with the specified detail message.

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail UnableToDeleteProviderException public UnableToDeleteProviderException(java.lang.String msg) Constructs a new UnableToDeleteProviderException with the specified detail message. Parameters: msg - the detail message

UnableToDeleteProviderException public UnableToDeleteProviderException() Constructs a new UnableToDeleteProviderException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip Interfaces AddressFactory ListeningPoint NameAddress Parameters SipListener SipProvider SipStack SipURL URI

Classes SipFactory

Exceptions ListeningPointUnavailableException SipException SipListenerAlreadyRegisteredException SipListenerNotRegisteredException SipParseException SipPeerUnavailableException TransactionDoesNotExistException UnableToDeleteProviderException

Package jain.protocol.ip.sip.header This package contains the classes representing SIP headers. See: Description

Interface Summary AcceptEncodingHeader

This interface represents the Accept-Encoding request-header.

AcceptHeader

This interface represents an Accept request-header.

AcceptLanguageHeader

This interface represents the Accept-Language request-header.

AllowHeader

This interface represents the Allow entity-header.

AuthorizationHeader

This interface represents the Authorization request-header.

CallIdHeader

This interface represents the Call-ID general-header.

ContactHeader

This interface represents the Contact general-header.

ContentEncodingHeader

This interface represents the Content-Encoding entity-header.

ContentLengthHeader

This interface represents the Content-Length entity-header.

ContentTypeHeader

This interface represents the Content-Type entity-header.

CSeqHeader

This interface represents the CSeq (command sequence) general-header.

DateHeader

This interface represents the Date general header.

EncodingHeader

This interface represents any header that contains an encoding value.

EncryptionHeader

This interface represents the Encryption general-header.

EndPointHeader

This interface represents any header that indicates an endpoint of a Message's path.

ExpiresHeader

This interface represents the Expires entity-header.

FromHeader

This interface represents the From general-header.

Header

This interface represents a generic SIP header.

HeaderFactory

This interface provides factory methods to allow an application create Header objects from a particular JAIN SIP implementation.

HeaderIterator

HideHeader

This interface represents the Hide request-header.

MaxForwardsHeader

This interface represents the Max-Forwards request-header.

NameAddressHeader

This interface represents any header that contains a NameAddress value.

OptionTagHeader

This interface represents any header that contains an option tag value.

OrganizationHeader

This interface represents the Organization general-header.

ParametersHeader

This interface represents any header that contains parameters.

PriorityHeader

This interface represents the Priority request-header.

ProductHeader

This interface represents a header that contains product information.

ProxyAuthenticateHeader

This interface represents the Proxy-Authenticate response-header.

ProxyAuthorizationHeader This interface represents the Proxy-Authorization request-header. ProxyRequireHeader

This interface represents the Proxy-Require request-header.

RecordRouteHeader

This interface represents the Record-Route general-header.

RequireHeader

This interface representshe Require request-header.

ResponseKeyHeader

This interface represents the Response-Key request-header.

RetryAfterHeader

This interface represents the Retry-After general-header.

RouteHeader

This interface represents the Route request-header.

SecurityHeader

This interface represents headers used in SIP security.

ServerHeader

This interface represents the Server response-header.

SubjectHeader

This interface represents the Subject request-header.

TimeStampHeader

This interface represents the Timestamp general-header.

ToHeader

This interface represents the To general-header.

UnsupportedHeader

This interface represents the Unsupported response-header.

UserAgentHeader

This interface represents the User-Agent general-header.

ViaHeader

This interface represents the Via general-header.

WarningHeader

This interface represents the Warning response-header.

WWWAuthenticateHeader This interface represents the WWW-Authenticate response-header.

Exception Summary

The HeaderParseException is thrown by an implementation that cannot parse HeaderParseException a header value when an application asks a Message for an API-defined Header object (e.g.

Package jain.protocol.ip.sip.header Description This package contains the classes representing SIP headers. Messages may contain multiple instances of certain Headers. The order of these Headers within a Message is significant. The order of all Headers within a Message is also significant. Additionally, Headers which are hop-by-hop must appear before any Headers which are end-to-end. Proxies should not reorder Headers. Proxies add ViaHeaders and may add other hop-by-hop Headers. They can modify certain Headers, such as MaxForwardsHeaders and "fix up" the ViaHeaders with "received" parameters. Proxies must not alter any Headers that are authenticated. Other Headers can be added as required; a server must ignore Headers that it does not understand. A proxy must not remove or modify Headers that it does not understand. If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface AcceptEncodingHeader public interface AcceptEncodingHeader extends EncodingHeader This interface represents the Accept-Encoding request-header. A client includes an AcceptEncodingHeader in a Request to tell the server what coding schemes are acceptable in the Response e.g. compress, gzip. If no AcceptEncodingHeader is present in a Request, the server may assume that the client will accept any content coding. If an AcceptEncodingHeader is present, and if the server cannot send a Response which is acceptable according to the AcceptEncodingHeader, then the server should return a Response with a status code of NOT_ACCEPTABLE. An empty encoding value indicates none are acceptable. Version: 0.7 See Also: EncodingHeader

Field Summary static java.lang.String name

Name of AcceptEncodingHeader

Methods inherited from interface jain.protocol.ip.sip.header.EncodingHeader getEncoding, setEncoding

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of AcceptEncodingHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface AcceptHeader public interface AcceptHeader extends ContentTypeHeader This interface represents an Accept request-header. It can be used in to specify media-ranges which are acceptable for the response. AcceptHeaders can be used to indicate that the request is specifically limited to a small set of desired types. The specification of the acceptable media is split into type and subtype. An AcceptHeader may be followed by one or more parameters applicable to the media-range. Q-values allow the user to indicate the relative degree of preference for that media-range, using the qvalue scale from 0 to 1. (If no q-value is present, the media-range should be treated as having a q-value of 1.) If no AcceptHeader is present in a Request, then it is assumed that the client accepts media of type "application" and subType "sdp". If an AcceptHeader is present, and if the server cannot send a response which is acceptable according to the combined Accept field value, then the server should send a ResponseMessage with a NOT_ACCEPTABLE status code. Version: 0.7 See Also: ContentTypeHeader

Field Summary static java.lang.String name

Name of AcceptHeader

Fields inherited from interface jain.protocol.ip.sip.header.ContentTypeHeader name

Method Summary boolean allowsAllContentSubTypes()

Gets boolean value to indicate if the AcceptHeader allows all media sub-types (i.e. boolean allowsAllContentTypes()

Gets boolean value to indicate if the AcceptHeader allows all media types (i.e.

float getQValue()

Gets q-value of media-range in AcceptHeader (Returns negative float if no q-value exists) boolean hasQValue()

Gets boolean value to indicate if AcceptHeader has q-value void removeQValue()

Removes q-value of media-range in AcceptHeader (if it exists) void setQValue(float qValue)

Sets q-value for media-range in AcceptHeader Q-values allow the user to indicate the relative degree of preference for that media-range, using the qvalue scale from 0 to 1.

Methods inherited from interface jain.protocol.ip.sip.header.ContentTypeHeader getContentSubType, getContentType, setContentSubType, setContentType

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of AcceptHeader

Method Detail

allowsAllContentTypes public boolean allowsAllContentTypes() Gets boolean value to indicate if the AcceptHeader allows all media types (i.e. content type is "*") Returns: boolean value to indicate if the AcceptHeader allows all media types

allowsAllContentSubTypes public boolean allowsAllContentSubTypes() Gets boolean value to indicate if the AcceptHeader allows all media sub-types (i.e. content sub-type is "*") Returns: boolean value to indicate if the AcceptHeader allows all media sub-types

setQValue public void setQValue(float qValue) throws SipParseException Sets q-value for media-range in AcceptHeader Q-values allow the user to indicate the relative degree of preference for that media-range, using the qvalue scale from 0 to 1. (If no q-value is present, the media-range should be treated as having a q-value of 1.) Parameters: qValue - q-value Throws: SipParseException - if qValue is not accepted by implementation

getQValue public float getQValue() Gets q-value of media-range in AcceptHeader (Returns negative float if no q-value exists) Returns: q-value of media-range

hasQValue public boolean hasQValue() Gets boolean value to indicate if AcceptHeader has q-value Returns: boolean value to indicate if AcceptHeader has q-value

removeQValue public void removeQValue() Removes q-value of media-range in AcceptHeader (if it exists) If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface AcceptLanguageHeader public interface AcceptLanguageHeader extends Header This interface represents the Accept-Language request-header. AcceptLanguageHeader can be used in a Request to allow the client to indicate to the server in which language it would prefer to receive reason phrases, session descriptions or status responses carried as message bodies. The q-value is used in a similar manner to AcceptHeader to indicate degrees of preference. Version: 0.7 See Also: AcceptHeader

Field Summary static java.lang.String name

Name of AcceptLanguageHeader

Method Summary java.lang.String getLanguageRange()

Gets the language-range of AcceptLanguageHeader float getQValue()

Gets the q-value of language-range in AcceptLanguageHeader (returns negative float if no q-value exists) boolean hasQValue()

Indicates whether or not a q-value exists in AcceptLanguageHeader void removeQValue()

Removes q-value from AcceptLanguageHeader (if it exists) void setLanguageRange(java.lang.String languageRange)

Sets the language-range of AcceptLanguageHeader

void setQValue(float qValue)

Sets q-value for media-range in AcceptLanguageHeader Q-values allow the user to indicate the relative degree of preference for that language-range, using the qvalue scale from 0 to 1.

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of AcceptLanguageHeader

Method Detail getLanguageRange public java.lang.String getLanguageRange() Gets the language-range of AcceptLanguageHeader Returns: language-range of AcceptLanguageHeader

getQValue public float getQValue() Gets the q-value of language-range in AcceptLanguageHeader (returns negative float if no q-value exists) Returns: the q-value of language-range in AcceptLanguageHeader

hasQValue public boolean hasQValue() Indicates whether or not a q-value exists in AcceptLanguageHeader Returns: boolean to indicate whether or not a q-value exists in AcceptLanguageHeader

setLanguageRange public void setLanguageRange(java.lang.String languageRange) throws java.lang.IllegalArgumentException, SipParseException Sets the language-range of AcceptLanguageHeader Parameters: languageRange - language-range of AcceptLanguageHeader Throws: java.lang.IllegalArgumentException - if languageRange is null SipParseException - if languageRange is not accepted by implementation

setQValue public void setQValue(float qValue) throws SipParseException Sets q-value for media-range in AcceptLanguageHeader Q-values allow the user to indicate the relative degree of preference for that language-range, using the qvalue scale from 0 to 1. (If no q-value is present, the language-range should be treated as having a q-value of 1.) Parameters: qValue - q-value Throws: SipParseException - if qValue is not accepted by implementation

removeQValue public void removeQValue()

Removes q-value from AcceptLanguageHeader (if it exists) If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface AllowHeader public interface AllowHeader extends Header This interface represents the Allow entity-header. The AllowHeader specifies a method supported by the resource identified by the Request-URI of a Request. An AllowHeader must be present in a Response with a status code METHOD_NOT_ALLOWED, and should be present in a Response to an OPTIONS Request Version: 0.7

Field Summary static java.lang.String name

Name of AllowHeader

Method Summary java.lang.String getMethod()

Gets method of AllowHeader void setMethod(java.lang.String method)

Sets method of AllowHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of AllowHeader

Method Detail getMethod public java.lang.String getMethod() Gets method of AllowHeader Returns: method of AllowHeader

setMethod public void setMethod(java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException Sets method of AllowHeader Parameters: method - method Throws: java.lang.IllegalArgumentException - if method is null SipParseException - if method is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface AuthorizationHeader public interface AuthorizationHeader extends SecurityHeader This interface represents the Authorization request-header. A user agent that wishes to authenticate itself with a server - usually, but not necessarily, after receiving an UNAUTHORIZED Response - may do so by including an AuthorizationHeader with the Request. The AuthorizationHeader consists of credentials containing the authentication information of the user agent for the realm of the resource being requested. Version: 0.7 See Also: SecurityHeader

Field Summary static java.lang.String name

Name of AuthorizationHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail

name public static final java.lang.String name Name of AuthorizationHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface CallIdHeader public interface CallIdHeader extends Header This interface represents the Call-ID general-header. CallIdHeader uniquely identifies a particular invitation or all registrations of a particular client. Note that a single multimedia conference can give rise to several calls with different Call-IDs, e.g., if a user invites a single individual several times to the same (long-running) conference. For an INVITE Request, a callee user agent server should not alert the user if the user has responded previously to the Call-ID in the INVITE Request. If the user is already a member of the conference and the conference parameters contained in the session description have not changed, a callee user agent server may silently accept the call, regardless of the Call-ID. An invitation for an existing Call-ID or session can change the parameters of the conference. A client application MAY decide to simply indicate to the user that the conference parameters have been changed and accept the invitation automatically or it may require user confirmation. A user may be invited to the same conference or call using several different CallIdHeaders. If desired, the client may use identifiers within the session description to detect this duplication. For example, SDP contains a session id and version number in the origin (o) field. The REGISTER and OPTIONS Requests use the CallIdHeader to unambiguously match Requests and Responses. All REGISTER Requests issued by a single client should use the same CallIdHeader, at least within the same boot cycle. Version: 0.7

Field Summary static java.lang.String name

Name of CallIdHeader

Method Summary java.lang.String getCallId()

Gets Call-Id of CallIdHeader void setCallId(java.lang.String callId)

Sets Call-Id of CallIdHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of CallIdHeader

Method Detail getCallId public java.lang.String getCallId() Gets Call-Id of CallIdHeader Returns: Call-Id of CallIdHeader

setCallId public void setCallId(java.lang.String callId) throws java.lang.IllegalArgumentException, SipParseException Sets Call-Id of CallIdHeader Parameters: callId - Call-Id Throws: java.lang.IllegalArgumentException - if callId is null SipParseException - if callId is not accepted by implementation If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ContactHeader public interface ContactHeader extends NameAddressHeader, ParametersHeader This interface represents the Contact general-header. A ContactHeader field can appear in INVITE, ACK and REGISTER Requests, and in Responses with any INFORMATIONAL, SUCCESS, REDIRECT, or AMBIGUOUS status codes. In general, it provides a URL where the user can be reached for further communications. INVITE and ACK Requests: INVITE and ACK Requests may contain ContactHeaders indicating from which location the request is originating. This allows the callee to send future Requests, such as BYE Requests, directly to the caller instead of through a series of proxies. The ViaHeader is not sufficient since the desired address may be that of a proxy. SUCCESS Responses for INVITE Requests: A user agent server sending a definitive, positive Response (SUCCESS) may insert a ContactHeader in the Response indicating the SIP address under which it is reachable most directly for future SIP Requests, such as an ACK Request, within the same Call-ID. The ContactHeader contains the address of the server itself or that of a proxy, e.g., if the host is behind a firewall. The value of this ContactHeader is copied into the Request-URI of subsequent Requests for this call if the response did not also contain a RecordRouteHeader. If the response also contains a RecordRouteHeader, the address in the ContactHeader is added as the last item in the RouteHeader. See RecordRouteHeader for details. The ContactHeader should not be cached across calls, as it may not represent the most desirable location for a particular destination address. INFORMATIONAL Responses for INVUTE Requests: A server sending an INFORMATIONAL Response may insert a ContactHeader. It has the same semantics in an INFORMATIONAL Response as a SUCCESS Response. Note that CANCEL Requests must not be sent to that address, but rather follow the same path as the original request. REGISTER Requests: REGISTER Requests may contain ContactHeaders indicating at which locations the user is reachable. The REGISTER Request defines a wildcard ContactHeader which must only be used with Expires set to 0 to remove all registrations for a particular user. An optional "expires" parameter indicates the desired expiration time of the registration. If a ContactHeader does not have an "expires" parameter, the ExpiresHeader field is used as the default value. If neither of these mechanisms is used, SIP URIs are assumed to expire after one hour. Other URI schemes have no expiration times. SUCCESS Responses for REGISTER Requests: A SUCCESS Response for a REGISTER Request may return all locations at which the user is currently reachable. An optional "expires" parameter indicates the expiration time of the registration. If a ContactHeader does not have an "expires" parameter, the value of

the ExpiresHeader indicates the expiration time. If neither mechanism is used, the expiration time specified in the request, explicitly or by default, is used. REDIRECTION and AMBIGUOUS Responses: The ContactHeader can be used with a REDIRECTION or AMBIGUOUS Response to indicate one or more alternate addresses to try. It can appear in Responses for BYE, INVITE and OPTIONS Requests. ContactHeaders contain URIs giving the new locations or user names to try, or may simply specify additional transport parameters. A REDIRECTION_MULTIPLE_CHOICES, REDIRECTION_MOVED_PERMANENTLY, REDIRECTION_MOVED_TEMPORARILY, or AMBIGUOUS Response should contain one or more ContactHeaders containing URIs of new addresses to be tried. A REDIRECTION_MOVED_PERMANENTLY or REDIRECTION_MOVED_TEMPORARILY Response may also give the same location and username that was being tried but specify additional transport parameters such as a different server or multicast address to try or a change of SIP transport from UDP to TCP or vice versa. The client copies the "user", "password", "host", "port" and "user-param" elements of the Contact URI into the Request-URI of the redirected request and directs the request to the address specified by the "maddr" and "port" parameters, using the transport protocol given in the "transport" parameter. If "maddr" is a multicast address, the value of "ttl" is used as the time-to-live value. Note that the ContactHeader field may also refer to a different entity than the one originally called. For example, a SIP call connected to GSTN gateway may need to deliver a special information announcement such as "The number you have dialed has been changed." A ContactHeader in a Response can contain any suitable URI indicating where the called party can be reached, not limited to SIP URLs. For example, it could contain URL's for phones, fax, or irc (if they were defined) or a mailto: URL. The following parameters are defined. q: The "qvalue" indicates the relative preference among the locations given. "qvalue" values are decimal numbers from 0 to 1, with higher values indicating higher preference. action: The "action" parameter is used only when registering with the REGISTER request. It indicates whether the client wishes that the server proxy or redirect future Requests intended for the client. If this parameter is not specified the action taken depends on server configuration. In its Response, the registrar should indicate the mode used. This parameter is ignored for other Requests. expires: The "expires" parameter indicates how long the URI is valid. The parameter is either a number indicating seconds or a quoted string containing a SIP-date. If this parameter is not provided, the value of the ExpiresHeader determines how long the URI is valid. Implementations may treat values larger than 2**32-1 (4294967295 seconds or 136 years) as equivalent to 2**32-1. Version: 0.7 See Also: NameAddressHeader, ParametersHeader, RecordRouteHeader

Field Summary static java.lang.String ACTION_PROXY

Proxy action constant static java.lang.String ACTION_REDIRECT

Redirect action constant static java.lang.String name

Name of ContactHeader

Method Summary java.lang.String getAction()

Gets action of ContactHeader (Returns null if action does not exist) java.lang.String getComment()

Gets comment of ContactHeader (Returns null if comment does not exist) java.util.Date getExpiresAsDate()

Gets expires as date of ContactHeader (Returns null if expires value does not exist) long getExpiresAsDeltaSeconds()

Gets expires as delta-seconds of ContactHeader (returns negative long if expires does not exist) float getQValue()

Gets q-value of ContactHeader (Returns negative float if comment does not exist) boolean hasAction()

Gets boolean value to indicate if ContactHeader has action boolean hasComment()

Gets boolean value to indicate if ContactHeader has comment boolean hasExpires()

Gets boolean value to indicate if ContactHeader has expires boolean hasQValue()

Gets boolean value to indicate if ContactHeader has q-value boolean isWildCard()

Returns boolean value indicating whether ContactHeader is a wild card void removeAction()

Removes action from ContactHeader (if it exists)

void removeComment()

Removes comment from ContactHeader (if it exists) void removeExpires()

Removes expires from ContactHeader (if it exists) void removeQValue()

Removes q-value from ContactHeader (if it exists) void setAction(java.lang.String action)

Sets action of ContactHeader void setComment(java.lang.String comment)

Sets comment of ContactHeader void setExpires(java.util.Date expiryDate)

Sets expires of ContactHeader to a date void setExpires(long expiryDeltaSeconds)

Sets expires of ContactHeader to a number of delta-seconds void setQvalue(float qValue)

Sets q-value of ContactHeader void setWildCard()

Sets ContactHeader to wild card (replaces NameAddress with "*")

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail ACTION_PROXY public static final java.lang.String ACTION_PROXY Proxy action constant

ACTION_REDIRECT public static final java.lang.String ACTION_REDIRECT Redirect action constant

name public static final java.lang.String name Name of ContactHeader

Method Detail isWildCard public boolean isWildCard() Returns boolean value indicating whether ContactHeader is a wild card Returns: boolean value indicating whether ContactHeader is a wild card

setWildCard public void setWildCard() Sets ContactHeader to wild card (replaces NameAddress with "*")

getComment public java.lang.String getComment() Gets comment of ContactHeader (Returns null if comment does not exist) Returns: comment of ContactHeader

hasComment public boolean hasComment() Gets boolean value to indicate if ContactHeader has comment Returns: boolean value to indicate if ContactHeader has comment

setComment public void setComment(java.lang.String comment) throws java.lang.IllegalArgumentException, SipParseException Sets comment of ContactHeader Parameters: comment - comment Throws: java.lang.IllegalArgumentException - if comment is null SipParseException - if comment is not accepted by implementation

removeComment public void removeComment() Removes comment from ContactHeader (if it exists)

getQValue public float getQValue() Gets q-value of ContactHeader (Returns negative float if comment does not exist) Returns: q-value of ContactHeader

hasQValue public boolean hasQValue() Gets boolean value to indicate if ContactHeader has q-value Returns: boolean value to indicate if ContactHeader has q-value

setQvalue public void setQvalue(float qValue) throws SipParseException Sets q-value of ContactHeader Parameters: qValue - q-value Throws: SipParseException - if qValue is not accepted by implementation

removeQValue public void removeQValue() Removes q-value from ContactHeader (if it exists)

setAction public void setAction(java.lang.String action) throws java.lang.IllegalArgumentException, SipParseException Sets action of ContactHeader Parameters: action - action Throws: java.lang.IllegalArgumentException - if action is null SipParseException - if action is not accepted by implementation

hasAction public boolean hasAction() Gets boolean value to indicate if ContactHeader has action Returns: boolean value to indicate if ContactHeader has action

removeAction public void removeAction() Removes action from ContactHeader (if it exists)

getAction public java.lang.String getAction() Gets action of ContactHeader (Returns null if action does not exist) Returns: action of ContactHeader

setExpires public void setExpires(long expiryDeltaSeconds) throws SipParseException Sets expires of ContactHeader to a number of delta-seconds Parameters: expiryDeltaSeconds - number of delta-seconds until expiry Throws: SipParseException - if expiryDeltaSeconds is not accepted by implementation

setExpires public void setExpires(java.util.Date expiryDate) throws java.lang.IllegalArgumentException,

SipParseException Sets expires of ContactHeader to a date Parameters: expiryDate - date of expiry Throws: java.lang.IllegalArgumentException - if expiryDate is null SipParseException - if expiryDate is not accepted by implementation

getExpiresAsDeltaSeconds public long getExpiresAsDeltaSeconds() Gets expires as delta-seconds of ContactHeader (returns negative long if expires does not exist) Returns: expires as delta-seconds of ContactHeader

hasExpires public boolean hasExpires() Gets boolean value to indicate if ContactHeader has expires Returns: boolean value to indicate if ContactHeader has expires

getExpiresAsDate public java.util.Date getExpiresAsDate() Gets expires as date of ContactHeader (Returns null if expires value does not exist) Returns: expires as date of ContactHeader

removeExpires public void removeExpires() Removes expires from ContactHeader (if it exists)

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ContentEncodingHeader public interface ContentEncodingHeader extends EncodingHeader This interface represents the Content-Encoding entity-header. A ContentEncodingHeader is used as a modifier to the "media-type". When present, its value indicates what additional content codings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the ContentTypeHeader. The ContentEncodingHeader is primarily used to allow a body to be compressed without losing the identity of its underlying media type. If multiple encodings have been applied to an entity, the ContentEncodingHeaders must be listed in the order in which they were applied. All content-coding values are case-insensitive. The Internet Assigned Numbers Authority (IANA) acts as a registry for content-coding values Clients may apply content encodings to the body in Requests. If the server is not capable of decoding the body, or does not recognize any of the content-coding values, it must send a UNSUPPORTED_MEDIA_TYPE Response, listing acceptable encodings in an AcceptEncodingHeader. A server may apply content encodings to the bodies in Response. The server must only use encodings listed in the AcceptEncodingHeader in the Response. Version: 0.7

Field Summary static java.lang.String name

Name of ContentEncodingHeader

Methods inherited from interface jain.protocol.ip.sip.header.EncodingHeader getEncoding, setEncoding

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of ContentEncodingHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ContentLengthHeader public interface ContentLengthHeader extends Header This interface represents the Content-Length entity-header. ContentLengthHeader indicates the size of the message-body, in decimal number of octets, sent to the recipient. Applications should use this field to indicate the size of the message-body to be transferred, regardless of the media type of the entity. Any Content-Length greater than or equal to zero is a valid value. If no body is present in a Message, then the Content-Length header field must be set to zero. Version: 0.7

Field Summary static java.lang.String name

Name of ContentLengthHeader

Method Summary int getContentLength()

Gets content-length of ContentLengthHeader void setContentLength(int contentLength)

Set content-length of ContentLengthHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of ContentLengthHeader

Method Detail setContentLength public void setContentLength(int contentLength) throws SipParseException Set content-length of ContentLengthHeader Parameters: contentLength - content-length Throws: SipParseException - if contentLength is not accepted by implementation

getContentLength public int getContentLength() Gets content-length of ContentLengthHeader Returns: content-length of ContentLengthHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ContentTypeHeader All Known Subinterfaces: AcceptHeader public interface ContentTypeHeader extends ParametersHeader This interface represents the Content-Type entity-header. A ContentTypeHeader indicates the media type of the entity-body sent to the recipient. There must be a ContentTypeHeader included in Messages which contain a body. The media-type is represented in the same manner as AcceptHeader. Version: 0.7 See Also: AcceptHeader

Field Summary static java.lang.String name

Name of ContentTypeHeader

Method Summary java.lang.String getContentSubType()

Gets media sub-type of ContentTypeHeader java.lang.String getContentType()

Gets media type of ContentTypeHeader void setContentSubType(java.lang.String contentSubType)

Sets value of media subtype in ContentTypeHeader void setContentType(java.lang.String ContentType)

Sets value of media type in ContentTypeHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of ContentTypeHeader

Method Detail getContentType public java.lang.String getContentType() Gets media type of ContentTypeHeader Returns: media type of ContentTypeHeader

getContentSubType public java.lang.String getContentSubType() Gets media sub-type of ContentTypeHeader Returns: media sub-type of ContentTypeHeader

setContentSubType public void setContentSubType(java.lang.String contentSubType) throws java.lang.IllegalArgumentException, SipParseException

Sets value of media subtype in ContentTypeHeader Parameters: subType - media sub-type Throws: java.lang.IllegalArgumentException - if sub-type is null SipParseException - if contentSubType is not accepted by implementation

setContentType public void setContentType(java.lang.String ContentType) throws java.lang.IllegalArgumentException, SipParseException Sets value of media type in ContentTypeHeader Parameters: type - media type Throws: java.lang.IllegalArgumentException - if type is null SipParseException - if contentType is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface CSeqHeader public interface CSeqHeader extends Header This interface represents the CSeq (command sequence) general-header. Clients must add the CSeqHeader to every Request. A CSeqHeader in a Request contains the Request method and a single decimal sequence number chosen by the requesting client, unique within a single value of Call-ID. The sequence number must be expressible as a 32-bit unsigned integer. The initial value of the sequence number is arbitrary, but must be less than 2**31. Consecutive Requests that differ in method, headers or body, but have the same CallIdHeader must contain strictly monotonically increasing and contiguous sequence numbers; sequence numbers do not wrap around. Retransmissions of the same Request carry the same sequence number, but an INVITE Request with a different message body or different headers (a "re-invitation") acquires a new, higher sequence number. A server must echo the CSeqHeader from the Request in its Response. If the method value is missing in the received CSeqHeader, the server fills it in appropriately. ACK and CANCEL Requests must contain the same CSeqHeader sequence number (but not method) as the INVITE Request they refer to, while a BYE Request cancelling an invitation must have a higher sequence number. A BYE Request with a CSeqHeader sequence number that is not higher should cause a BAD_REQUEST Response to be generated. A user agent server must remember the highest sequence number for any INVITE Request with the same CallIdHeader. The server must respond to, and then discard, any INVITE Request with a lower sequence number. All Requests spawned in a parallel search have the same CSeqHeader as the Request triggering the parallel search. The method value allows the client to distinguish the Response to an INVITE Request from that of a response to a CANCEL Request. CANCEL Requests can be generated by proxies; if they were to increase the sequence number, it might conflict with a later Request issued by the user agent for the same call. Forked Requests must have the same CSeqHeader as there would be ambiguity otherwise between these forked Requests and later BYE Requests issued by the client user agent. Version: 0.7

Field Summary

static java.lang.String name

Name of CSeqHeader

Method Summary java.lang.String getMethod()

Gets method of CSeqHeader int getSequenceNumber()

Gets sequence number of CSeqHeader void setMethod(java.lang.String method)

Set method of CSeqHeader void setSequenceNumber(int sequenceNumber)

Set sequence number of CSeqHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of CSeqHeader

Method Detail setSequenceNumber public void setSequenceNumber(int sequenceNumber) throws SipParseException Set sequence number of CSeqHeader Parameters: sequenceNumber - sequence number

Throws: SipParseException - if sequenceNumber is not accepted by implementation

setMethod public void setMethod(java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException Set method of CSeqHeader Parameters: method - method Throws: java.lang.IllegalArgumentException - if method is null SipParseException - if method is not accepted by implementation

getSequenceNumber public int getSequenceNumber() Gets sequence number of CSeqHeader Returns: sequence number of CSeqHeader

getMethod public java.lang.String getMethod() Gets method of CSeqHeader Returns: method of CSeqHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface DateHeader All Known Subinterfaces: ExpiresHeader, RetryAfterHeader public interface DateHeader extends Header This interface represents the Date general header. DateHeader reflects the time when a Request or Response is first sent. Thus, retransmissions have the same Date header field value as the original. The DateHeader can be used by simple end systems without a battery-backed clock to acquire a notion of current time. Version: 0.7

Field Summary static java.lang.String name

Name of DateHeader

Method Summary java.util.Date getDate()

Gets date of DateHeader (Returns null if date does not exist (this can only apply for ExpiresHeader subinterface - when the expires value is in delta seconds format) void setDate(java.util.Date date)

Sets date of DateHeader void setDate(java.lang.String date)

Sets date of DateHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of DateHeader

Method Detail getDate public java.util.Date getDate() Gets date of DateHeader (Returns null if date does not exist (this can only apply for ExpiresHeader subinterface - when the expires value is in delta seconds format) Returns: date of DateHeader

setDate public void setDate(java.util.Date date) throws java.lang.IllegalArgumentException, SipParseException Sets date of DateHeader Parameters: date - date Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

setDate public void setDate(java.lang.String date) throws java.lang.IllegalArgumentException, SipParseException

Sets date of DateHeader Parameters: date - date String Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface EncodingHeader All Known Subinterfaces: AcceptEncodingHeader, ContentEncodingHeader public interface EncodingHeader extends Header This interface represents any header that contains an encoding value. It is the super-interface of AcceptEncodingHeader and ContentEncodingHeader. Version: 0.7 See Also: AcceptEncodingHeader, ContentEncodingHeader

Method Summary java.lang.String getEncoding()

Gets the encoding of EncodingHeader void setEncoding(java.lang.String encoding)

Sets the encoding of EncodingHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Method Detail getEncoding public java.lang.String getEncoding() Gets the encoding of EncodingHeader Returns: encoding of EncodingHeader

setEncoding public void setEncoding(java.lang.String encoding) throws java.lang.IllegalArgumentException, SipParseException Sets the encoding of EncodingHeader Parameters: encoding - encoding Throws: java.lang.IllegalArgumentException - if encoding is null SipParseException - if encoding is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface EndPointHeader All Known Subinterfaces: FromHeader, ToHeader public interface EndPointHeader extends NameAddressHeader This interface represents any header that indicates an endpoint of a Message's path. It extends NameAddressHeader and is the super-interface of FromHeader and ToHeader. Version: 0.7 See Also: NameAddressHeader, FromHeader, ToHeader

Method Summary java.lang.String getTag()

Gets tag of EndPointHeader (Returns null if tag does not exist) boolean hasTag()

Gets boolean value to indicate if EndPointHeader has tag void removeTag()

Removes tag from EndPointHeader (if it exists) void setTag(java.lang.String tag)

Sets tag of EndPointHeader

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Method Detail getTag public java.lang.String getTag() Gets tag of EndPointHeader (Returns null if tag does not exist) Returns: tag of EndPointHeader

hasTag public boolean hasTag() Gets boolean value to indicate if EndPointHeader has tag Returns: boolean value to indicate if EndPointHeader has tag

setTag public void setTag(java.lang.String tag) throws java.lang.IllegalArgumentException, SipParseException Sets tag of EndPointHeader Parameters: tag - tag Throws: java.lang.IllegalArgumentException - if tag is null SipParseException - if tag is not accepted by implementation

removeTag public void removeTag() Removes tag from EndPointHeader (if it exists) If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ExpiresHeader All Known Subinterfaces: RetryAfterHeader public interface ExpiresHeader extends DateHeader This interface represents the Expires entity-header. The ExpiresHeader gives the date and time after which the message content expires. The ExpiresHeader is currently defined only for REGISTER and INVITE Requests and their corresponding Responses. In a REGISTER Request, the client indicates how long it wishes the registration to be valid. In the Response, the server indicates the earliest expiration time of all registrations. The server may choose a shorter time interval than that requested by the client, but should not choose a longer one. For INVITE Requests the caller can limit the validity of an invitation, for example, if a client wants to limit the time duration of a search or a conference invitation. A user interface may take this as a hint to leave the invitation window on the screen even if the user is not currently at the workstation. This also limits the duration of a search. If the INVITE Request expires before the search completes, the proxy returns a REQUEST_TIMEOUT Response. In a MOVED_TEMPORARILY Response, a server can advise the client of the maximal duration of the redirection. The value of this field can be either a date or an integer number of seconds (in decimal), measured from the receipt of the Request. The latter approach is preferable for short durations, as it does not depend on clients and servers sharing a synchronized clock. Implementations may treat values larger than 2**32-1 (4294967295 or 136 years) as equivalent to 2**32-1. Version: 0.7

Field Summary static java.lang.String name

Name of ExpiresHeader

Fields inherited from interface jain.protocol.ip.sip.header.DateHeader name

Method Summary long getDeltaSeconds()

Gets value of ExpiresHeader as delta-seconds (Returns -1 if expires value is not in delta-second format) boolean isDate()

Gets boolean value to indicate if expiry value of ExpiresHeader is in date format void setDeltaSeconds(long deltaSeconds)

Sets expires of ExpiresHeader as delta-seconds

Methods inherited from interface jain.protocol.ip.sip.header.DateHeader getDate, setDate, setDate

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of ExpiresHeader

Method Detail getDeltaSeconds public long getDeltaSeconds() Gets value of ExpiresHeader as delta-seconds (Returns -1 if expires value is not in delta-second format) Returns: value of ExpiresHeader as delta-seconds

setDeltaSeconds public void setDeltaSeconds(long deltaSeconds) throws SipParseException Sets expires of ExpiresHeader as delta-seconds Parameters: deltaSeconds - delta-seconds Throws: SipParseException - if deltaSeconds is not accepted by implementation

isDate public boolean isDate() Gets boolean value to indicate if expiry value of ExpiresHeader is in date format Returns: boolean value to indicate if expiry value of ExpiresHeader is in date format If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface FromHeader public interface FromHeader extends EndPointHeader This interface represents the From general-header. Requests and Responses must contain a FromHeader, indicating the initiator of the Request in its NameAddress. The FromHeader may contain a tag. The server copies the FromHeader from the Request to the Response. The optional "display-name" of the NameAddress is meant to be rendered by a human-user interface. A system should use the display name "Anonymous" if the identity of the client is to remain hidden. The SipURL of the NameAddress must not contain the transport, maddr, ttl, or headers elements. A server that receives a SipURL with these elements removes them before further processing. The tag may appear in the FromHeader of a Request. It must be present when it is possible that two instances of a user sharing a address can make call invitations with the same CallIdHeader. The tag value must be globally unique and cryptographically random with at least 32 bits of randomness. A single user maintains the same tag throughout the call identified by the CallIdHeader. The CallIdHeader, ToHeader and FromHeader are needed to identify a call leg. The distinction between call and call leg matters in calls with multiple Responses to a forked Request. Version: 0.7

Field Summary static java.lang.String name

Name of FromHeader

Methods inherited from interface jain.protocol.ip.sip.header.EndPointHeader getTag, hasTag, removeTag, setTag

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.header.Header

clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of FromHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface Header All Known Subinterfaces: AcceptEncodingHeader, AcceptHeader, AcceptLanguageHeader, AllowHeader, AuthorizationHeader, CallIdHeader, ContactHeader, ContentEncodingHeader, ContentLengthHeader, ContentTypeHeader, CSeqHeader, DateHeader, EncodingHeader, EncryptionHeader, EndPointHeader, ExpiresHeader, FromHeader, HideHeader, MaxForwardsHeader, NameAddressHeader, OptionTagHeader, OrganizationHeader, ParametersHeader, PriorityHeader, ProductHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ProxyRequireHeader, RecordRouteHeader, RequireHeader, ResponseKeyHeader, RetryAfterHeader, RouteHeader, SecurityHeader, ServerHeader, SubjectHeader, TimeStampHeader, ToHeader, UnsupportedHeader, UserAgentHeader, ViaHeader, WarningHeader, WWWAuthenticateHeader public interface Header extends java.lang.Cloneable, java.io.Serializable This interface represents a generic SIP header. A Header can be one of the following types: ● General header - can be in Request or Response ● Request header - can only be in Request ● Response header - can only be in Response ● Entity header - describes Message body or resource Messages may contain multiple instances of certain Headers. The order of these Headers within a Message is significant. The order of all Headers within a Message is also significant. Additionally, Headers which are hop-by-hop must appear before any Headers which are end-to-end. Proxies should not reorder Headers. Proxies add ViaHeaders and may add other hop-by-hop Headers. They can modify certain Headers, such as MaxForwardsHeaders and "fix up" the ViaHeaders with "received" parameters. Proxies must not alter any Headers that are authenticated. Other Headers can be added as required; a server must ignore Headers that it does not understand. A proxy must not remove or modify Headers that it does not understand. Version: 0.7

Method Summary java.lang.Object clone()

Creates and returns a copy of Header

boolean equals(java.lang.Object obj)

Indicates whether some other Object is "equal to" this Header (Note that obj must be have same class as this Header - which means it must be from same JAIN SIP implementation) java.lang.String getName()

Gets name of Header java.lang.String getValue()

Gets value of Header void setValue(java.lang.String value)

Sets value of Header java.lang.String toString()

Gets string representation of Header

Method Detail getName public java.lang.String getName() Gets name of Header Returns: name of Header

setValue public void setValue(java.lang.String value) throws java.lang.IllegalArgumentException, SipParseException Sets value of Header Parameters: value - value Throws: java.lang.IllegalArgumentException - if value is null SipParseException - if value is not accepted by implementation

getValue public java.lang.String getValue() Gets value of Header Returns: value of Header

toString public java.lang.String toString() Gets string representation of Header Overrides: toString in class java.lang.Object Returns: string representation of Header

equals public boolean equals(java.lang.Object obj) Indicates whether some other Object is "equal to" this Header (Note that obj must be have same class as this Header - which means it must be from same JAIN SIP implementation) Overrides: equals in class java.lang.Object Parameters: obj - the Object with which to compare this Header

clone public java.lang.Object clone() Creates and returns a copy of Header If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface HeaderFactory public interface HeaderFactory This interface provides factory methods to allow an application create Header objects from a particular JAIN SIP implementation.

Method Summary AcceptEncodingHeader createAcceptEncodingHeader(java.lang.String contentEncoding)

Creates an AcceptEncodingHeader with given content-encoding AcceptHeader createAcceptHeader(java.lang.String contentType,

java.lang.String contentSubType) Creates an AcceptHeader based on the specified type and subType AcceptLanguageHeader createAcceptLanguageHeader(java.lang.String languageRange)

Creates AcceptLanguageHeader based on given language-range AllowHeader createAllowHeader(java.lang.String method)

Creates an AllowHeader based on given method AuthorizationHeader createAuthorizationHeader(java.lang.String scheme)

Creates an AuthorizationHeader based on given scheme CallIdHeader createCallIdHeader(java.lang.String callId)

Creates a CallIdHeader based on given Call-Id ContactHeader createContactHeader()

Creates a wildcard ContactHeader. ContactHeader createContactHeader(NameAddress nameAddress)

Creates a ContactHeader based on given NameAddress ContentEncodingHeader createContentEncodingHeader(java.lang.String contentEncoding)

Creates a ContentEncodingHeader based on given content-encoding ContentLengthHeader createContentLengthHeader(int contentLength)

Creates a ContentLengthHeader based on given content-length ContentTypeHeader createContentTypeHeader(java.lang.String contentType,

java.lang.String contentSubType) Creates a ContentTypeHeader based on given media type and sub-type CSeqHeader createCSeqHeader(int sequenceNumber, java.lang.String method)

Creates a CSeqHeader based on given sequence number and method DateHeader createDateHeader(java.util.Date date)

Creates an DateHeader based on given Date DateHeader createDateHeader(java.lang.String date)

Creates a DateHeader based on given date string EncryptionHeader createEncryptionHeader(java.lang.String scheme)

Creates an EncryptionHeader based on given scheme

ExpiresHeader createExpiresHeader(java.util.Date date)

Creates an ExpiresHeader based on given date ExpiresHeader createExpiresHeader(long deltaSeconds)

Creates an ExpiresHeader based on given number of delta-seconds ExpiresHeader createExpiresHeader(java.lang.String date)

Creates an ExpiresHeader based on given date string FromHeader createFromHeader(NameAddress nameAddress)

Creates a FromHeader based on given NameAddress Header createHeader(java.lang.String name, java.lang.String value)

Creates a Header based on given token and value HideHeader createHideHeader(java.lang.String hide)

Creates a HideHeader based on hide value MaxForwardsHeader createMaxForwardsHeader(int maxForwards)

Creates a MaxForwardsHeader based on given number of max-forwards OrganizationHeader createOrganizationHeader(java.lang.String organization)

Creates an OrganizationHeader based on given organization PriorityHeader createPriorityHeader(java.lang.String priority)

Creates a PriorityHeader based on given priority ProxyAuthenticateHeader createProxyAuthenticateHeader(java.lang.String scheme)

Creates a ProxyAuthenticateHeader based on given scheme ProxyAuthorizationHeader createProxyAuthorizationHeader(java.lang.String scheme)

Creates a ProxyAuthorizationHeader based on given scheme ProxyRequireHeader createProxyRequireHeader(java.lang.String optionTag)

Creates a ProxyRequireHeader based on given option tag RecordRouteHeader createRecordRouteHeader(NameAddress nameAddress)

Creates a RecordRouteHeader based on given NameAddress RequireHeader createRequireHeader(java.lang.String optionTag)

Creates a RequireHeader based on given option tag ResponseKeyHeader createResponseKeyHeader(java.lang.String scheme)

Creates a ResponseKeyHeader based on given scheme RetryAfterHeader createRetryAfterHeader(java.util.Date date)

Creates a RetryAfterHeader based on given date RetryAfterHeader createRetryAfterHeader(long deltaSeconds)

Creates a RetryAfterHeader based on given number of delta-seconds RetryAfterHeader createRetryAfterHeader(java.lang.String date)

Creates a RetryAfterHeader based on given date string RouteHeader createRouteHeader(NameAddress nameAddress)

Creates a RouteHeader based on given NameAddresss ServerHeader createServerHeader(java.util.List products)

Creates a ServerHeader based on given List of products (Note that the Objects in the List must be Strings)

SubjectHeader createSubjectHeader(java.lang.String subject)

Creates a SubjectHeader based on given subject TimeStampHeader createTimeStampHeader(float timeStamp)

Creates a TimeStampHeader based on given timestamp ToHeader createToHeader(NameAddress nameAddress)

Creates a ToHeader based on given NameAddress UnsupportedHeader createUnsupportedHeader(java.lang.String optionTag)

Creates a UnsupportedHeader based on given option tag UserAgentHeader createUserAgentHeader(java.lang.String[] products)

Creates a UserAgentHeader based on given List of products (Note that the Objects in the List must be Strings) ViaHeader createViaHeader(java.net.InetAddress host)

Creates a ViaHeader based on given host ViaHeader createViaHeader(java.net.InetAddress host, int port,

java.lang.String transport) Creates a ViaHeader based on given host, port and transport ViaHeader createViaHeader(java.net.InetAddress host,

java.lang.String transport) Creates a ViaHeader based on given host and transport ViaHeader createViaHeader(int port, java.net.InetAddress host)

Creates a ViaHeader based on given host and port ViaHeader createViaHeader(int port, java.lang.String host)

Creates a ViaHeader based on given host and port ViaHeader createViaHeader(java.lang.String host)

Creates a ViaHeader based on given host ViaHeader createViaHeader(java.lang.String host, int port,

java.lang.String transport) Creates a ViaHeader based on given host, port and transport ViaHeader createViaHeader(java.lang.String host,

java.lang.String transport) Creates a ViaHeader based on given host and transport WarningHeader createWarningHeader(int code, java.net.InetAddress host,

java.lang.String text) Creates a WarningHeader based on given code, agent host and text WarningHeader createWarningHeader(int code, java.lang.String host,

java.lang.String text) Creates a WarningHeader based on given code, agent host and text WWWAuthenticateHeader createWWWAuthenticateHeader(java.lang.String scheme)

Creates a WWWAuthenticateHeader based on given scheme

Method Detail

createAcceptEncodingHeader public AcceptEncodingHeader createAcceptEncodingHeader(java.lang.String contentEncoding) throws java.lang.IllegalArgumentException, SipParseException Creates an AcceptEncodingHeader with given content-encoding Parameters: contentEncoding - the content-cenoding Throws: java.lang.IllegalArgumentException - if contentEncoding is null SipParseException - if contentEncoding is not accepted by implementation

createAcceptHeader public AcceptHeader createAcceptHeader(java.lang.String contentType, java.lang.String contentSubType) throws java.lang.IllegalArgumentException, SipParseException Creates an AcceptHeader based on the specified type and subType Parameters: type - media type subType - media sub-type Throws: java.lang.IllegalArgumentException - if type or sub-type is null SipParseException - if contentType or contentSubType is not accepted by implementation

createAcceptLanguageHeader public AcceptLanguageHeader createAcceptLanguageHeader(java.lang.String languageRange) throws java.lang.IllegalArgumentException, SipParseException Creates AcceptLanguageHeader based on given language-range Parameters: languageRange - language-range Throws: java.lang.IllegalArgumentException - if languageRange is null SipParseException - if languageRange is not accepted by implementation

createAllowHeader public AllowHeader createAllowHeader(java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException Creates an AllowHeader based on given method Parameters: method - method Throws: java.lang.IllegalArgumentException - if method is null SipParseException - if method is not accepted by implementation

createAuthorizationHeader public AuthorizationHeader createAuthorizationHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Creates an AuthorizationHeader based on given scheme Parameters: scheme - authentication scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

createCallIdHeader public CallIdHeader createCallIdHeader(java.lang.String callId) throws java.lang.IllegalArgumentException, SipParseException Creates a CallIdHeader based on given Call-Id Parameters: callId - call-id Throws: java.lang.IllegalArgumentException - if callId is null SipParseException - if callId is not accepted by implementation

createContactHeader public ContactHeader createContactHeader(NameAddress nameAddress) throws java.lang.IllegalArgumentException, SipParseException

Creates a ContactHeader based on given NameAddress Parameters: nameAddress - NameAddress Throws: java.lang.IllegalArgumentException - if nameAddress is null or not from same JAIN SIP implementation

createContactHeader public ContactHeader createContactHeader() Creates a wildcard ContactHeader. This is used in RegisterMessages to indicate to the server that it should remove all locations the at which the user is currently available

createContentEncodingHeader public ContentEncodingHeader createContentEncodingHeader(java.lang.String contentEncoding) throws java.lang.IllegalArgumentException, SipParseException Creates a ContentEncodingHeader based on given content-encoding Parameters: contentEncoding - content-encoding Throws: java.lang.IllegalArgumentException - if contentEncoding is null SipParseException - if contentEncoding is not accepted by implementation

createContentLengthHeader public ContentLengthHeader createContentLengthHeader(int contentLength) throws SipParseException Creates a ContentLengthHeader based on given content-length Parameters: contentLength - content-length Throws: SipParseException - if contentLength is not accepted by implementation

createContentTypeHeader public ContentTypeHeader createContentTypeHeader(java.lang.String contentType, java.lang.String contentSubType) throws java.lang.IllegalArgumentException, SipParseException

Creates a ContentTypeHeader based on given media type and sub-type Parameters: type - media type subType - media sub-type Throws: java.lang.IllegalArgumentException - if type or subtype are null SipParseException - if contentType or contentSubType is not accepted by implementation

createCSeqHeader public CSeqHeader createCSeqHeader(int sequenceNumber, java.lang.String method) throws java.lang.IllegalArgumentException, SipParseException Creates a CSeqHeader based on given sequence number and method Parameters: sequenceNumber - sequence number method - method Throws: java.lang.IllegalArgumentException - if method is null SipParseException - if sequenceNumber or method are not accepted by implementation

createDateHeader public DateHeader createDateHeader(java.lang.String date) throws java.lang.IllegalArgumentException, SipParseException Creates a DateHeader based on given date string Parameters: date - date string Throws: java.lang.IllegalArgumentException - if date string is null SipParseException - if date is not accepted by implementation

createDateHeader public DateHeader createDateHeader(java.util.Date date) throws java.lang.IllegalArgumentException, SipParseException Creates an DateHeader based on given Date Parameters: date - Date Throws:

java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

createEncryptionHeader public EncryptionHeader createEncryptionHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Creates an EncryptionHeader based on given scheme Parameters: scheme - scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

createExpiresHeader public ExpiresHeader createExpiresHeader(long deltaSeconds) throws SipParseException Creates an ExpiresHeader based on given number of delta-seconds Parameters: deltaSeconds - delta-seconds Throws: SipParseException - if deltaSeconds is not accepted by implementation

createExpiresHeader public ExpiresHeader createExpiresHeader(java.util.Date date) throws java.lang.IllegalArgumentException, SipParseException Creates an ExpiresHeader based on given date Parameters: date - date Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

createExpiresHeader public ExpiresHeader createExpiresHeader(java.lang.String date) throws java.lang.IllegalArgumentException, SipParseException

Creates an ExpiresHeader based on given date string Parameters: date - date string Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

createFromHeader public FromHeader createFromHeader(NameAddress nameAddress) throws java.lang.IllegalArgumentException, SipParseException Creates a FromHeader based on given NameAddress Parameters: nameAddress - NameAddress Throws: java.lang.IllegalArgumentException - if nameAddress is null or not from same JAIN SIP implementation

createHeader public Header createHeader(java.lang.String name, java.lang.String value) throws java.lang.IllegalArgumentException, SipParseException Creates a Header based on given token and value Parameters: name - name value - value Throws: java.lang.IllegalArgumentException - if name or value are null SipParseException - if name or value are not accepted by implementation

createHideHeader public HideHeader createHideHeader(java.lang.String hide) throws java.lang.IllegalArgumentException, SipParseException Creates a HideHeader based on hide value Parameters: hide - hide value Throws: java.lang.IllegalArgumentException - if hide is null SipParseException - if hide is not accepted by implementation

createMaxForwardsHeader public MaxForwardsHeader createMaxForwardsHeader(int maxForwards) throws SipParseException Creates a MaxForwardsHeader based on given number of max-forwards Parameters: maxForwards - number of max-forwards Throws: SipParseException - if maxForwards is not accepted by implementation

createOrganizationHeader public OrganizationHeader createOrganizationHeader(java.lang.String organization) throws java.lang.IllegalArgumentException, SipParseException Creates an OrganizationHeader based on given organization Parameters: organization - organization Throws: java.lang.IllegalArgumentException - if organization is null SipParseException - if organization is not accepted by implementation

createPriorityHeader public PriorityHeader createPriorityHeader(java.lang.String priority) throws java.lang.IllegalArgumentException, SipParseException Creates a PriorityHeader based on given priority Parameters: priority - priority Throws: java.lang.IllegalArgumentException - if priority is null SipParseException - if priority is not accepted by implementation

createProxyAuthenticateHeader public ProxyAuthenticateHeader createProxyAuthenticateHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException

Creates a ProxyAuthenticateHeader based on given scheme Parameters: scheme - authentication scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

createProxyAuthorizationHeader public ProxyAuthorizationHeader createProxyAuthorizationHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Creates a ProxyAuthorizationHeader based on given scheme Parameters: scheme - authentication scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

createProxyRequireHeader public ProxyRequireHeader createProxyRequireHeader(java.lang.String optionTag) throws java.lang.IllegalArgumentException, SipParseException Creates a ProxyRequireHeader based on given option tag Parameters: optionTag - option tag Throws: java.lang.IllegalArgumentException - if optionTag is null SipParseException - if scheme is not accepted by implementation

createRecordRouteHeader public RecordRouteHeader createRecordRouteHeader(NameAddress nameAddress) throws java.lang.IllegalArgumentException, SipParseException Creates a RecordRouteHeader based on given NameAddress Parameters: nameAddress - NameAddress Throws:

java.lang.IllegalArgumentException - if nameAddress is null or not from same JAIN SIP implementation

createRequireHeader public RequireHeader createRequireHeader(java.lang.String optionTag) throws java.lang.IllegalArgumentException, SipParseException Creates a RequireHeader based on given option tag Parameters: optionTag - option tag Throws: java.lang.IllegalArgumentException - if optionTag is null SipParseException - if optionTag is not accepted by implementation

createResponseKeyHeader public ResponseKeyHeader createResponseKeyHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Creates a ResponseKeyHeader based on given scheme Parameters: scheme - scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

createRetryAfterHeader public RetryAfterHeader createRetryAfterHeader(long deltaSeconds) throws SipParseException Creates a RetryAfterHeader based on given number of delta-seconds Parameters: deltaSeconds - number of delta-seconds Throws: SipParseException - if deltaSeconds is not accepted by implementation

createRetryAfterHeader public RetryAfterHeader createRetryAfterHeader(java.util.Date date) throws java.lang.IllegalArgumentException, SipParseException Creates a RetryAfterHeader based on given date

Parameters: date - date Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

createRetryAfterHeader public RetryAfterHeader createRetryAfterHeader(java.lang.String date) throws java.lang.IllegalArgumentException, SipParseException Creates a RetryAfterHeader based on given date string Parameters: date - date string Throws: java.lang.IllegalArgumentException - if date is null SipParseException - if date is not accepted by implementation

createRouteHeader public RouteHeader createRouteHeader(NameAddress nameAddress) throws java.lang.IllegalArgumentException, SipParseException Creates a RouteHeader based on given NameAddresss Parameters: nameAddress - NameAddress Throws: java.lang.IllegalArgumentException - if nameAddress is null or not from same JAIN SIP implementation

createServerHeader public ServerHeader createServerHeader(java.util.List products) throws java.lang.IllegalArgumentException, SipParseException Creates a ServerHeader based on given List of products (Note that the Objects in the List must be Strings) Parameters: products - products Throws: java.lang.IllegalArgumentException - if products is null, empty, or contains any null elements, or contains any non-String objects SipParseException - if any element of products is not accepted by implementation

createSubjectHeader public SubjectHeader createSubjectHeader(java.lang.String subject) throws java.lang.IllegalArgumentException, SipParseException Creates a SubjectHeader based on given subject Parameters: subject - subject Throws: java.lang.IllegalArgumentException - if subject is null SipParseException - if subject is not accepted by implementation

createTimeStampHeader public TimeStampHeader createTimeStampHeader(float timeStamp) throws SipParseException Creates a TimeStampHeader based on given timestamp Parameters: timeStamp - time stamp Throws: SipParseException - if timestamp is not accepted by implementation

createToHeader public ToHeader createToHeader(NameAddress nameAddress) throws java.lang.IllegalArgumentException, SipParseException Creates a ToHeader based on given NameAddress Parameters: nameAddress - NameAddress Throws: java.lang.IllegalArgumentException - if nameAddress is null or not from same JAIN SIP implementation

createUnsupportedHeader public UnsupportedHeader createUnsupportedHeader(java.lang.String optionTag) throws java.lang.IllegalArgumentException, SipParseException Creates a UnsupportedHeader based on given option tag Parameters: optionTag - option tag Throws:

java.lang.IllegalArgumentException - if optionTag is null SipParseException - if optionTag is not accepted by implementation

createUserAgentHeader public UserAgentHeader createUserAgentHeader(java.lang.String[] products) throws java.lang.IllegalArgumentException, SipParseException Creates a UserAgentHeader based on given List of products (Note that the Objects in the List must be Strings) Parameters: products - products Throws: java.lang.IllegalArgumentException - if products is null, empty, or contains any null elements, or contains any non-String objects SipParseException - if any element of products is not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

createViaHeader public ViaHeader createViaHeader(int port, java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host and port Parameters: host - host port - port Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host or port is not accepted by implementation

createViaHeader public ViaHeader createViaHeader(int port, java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host and port Parameters: host - host port - port Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host or port is not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.lang.String host, java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host and transport Parameters: host - host transport - transport Throws: java.lang.IllegalArgumentException - if host or transport are null SipParseException - if host or transport are not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.net.InetAddress host, java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host and transport Parameters: host - host transport - transport Throws: java.lang.IllegalArgumentException - if host or transport are null SipParseException - if host or transport are not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.net.InetAddress host, int port, java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host, port and transport Parameters: host - host port - port transport - transport Throws: java.lang.IllegalArgumentException - if host or transport are null SipParseException - if host, port or transport are not accepted by implementation

createViaHeader public ViaHeader createViaHeader(java.lang.String host, int port, java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Creates a ViaHeader based on given host, port and transport Parameters: host - host port - port transport - transport Throws: java.lang.IllegalArgumentException - if host or transport are null

SipParseException - if host, port or transport are not accepted by implementation

createWarningHeader public WarningHeader createWarningHeader(int code, java.net.InetAddress host, java.lang.String text) throws java.lang.IllegalArgumentException, SipParseException Creates a WarningHeader based on given code, agent host and text Parameters: code - code host - agent host text - text Throws: java.lang.IllegalArgumentException - if host or text are is null SipParseException - if code, host or text are not accepted by implementation

createWarningHeader public WarningHeader createWarningHeader(int code, java.lang.String host, java.lang.String text) throws java.lang.IllegalArgumentException, SipParseException Creates a WarningHeader based on given code, agent host and text Parameters: code - code host - agent host text - text Throws: java.lang.IllegalArgumentException - if host or text are is null SipParseException - if code, host or text are not accepted by implementation

createWWWAuthenticateHeader public WWWAuthenticateHeader createWWWAuthenticateHeader(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Creates a WWWAuthenticateHeader based on given scheme Parameters: scheme - authentication scheme Throws:

java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface HeaderIterator public interface HeaderIterator

Method Summary boolean hasNext()

Header next()

Method Detail next public Header next() throws HeaderParseException, java.util.NoSuchElementException

hasNext public boolean hasNext() If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface HideHeader public interface HideHeader extends Header This interface represents the Hide request-header. A client uses the HideHeader to indicate that it wants the path comprised of the ViaHeaders to be hidden from subsequent proxies and user agents. It can take two forms: route HideHeader and hop HideHeader. HideHeaders are typically added by the client user agent, but may be added by any proxy along the path. If a Request contains the route HideHeader, all following proxies should hide their previous hop. If a Request contains the hop HideHeader, only the next proxy should hide the previous hop and then remove the HideHeader unless it also wants to remain anonymous. A server hides the previous hop by encrypting the host and port of the top-most ViaHeader with an algorithm of its choice. Servers should add additional "salt" to the host and port information prior to encryption to prevent malicious downstream proxies from guessing earlier parts of the path based on seeing identical encrypted ViaHeaders. Hidden ViaHeaders are marked with the hidden ViaHeader option. A server that is capable of hiding ViaHeaders must attempt to decrypt all ViaHeaders marked as hidden to perform loop detection. Servers that are not capable of hiding can ignore hidden ViaHeaders in their loop detection algorithm. If hidden ViaHeaders were not marked, a proxy would have to decrypt all ViaHeaders to detect loops, just in case one was encrypted, as the hop HideHeader may have been removed along the way. A host must not add such a hop HideHeader unless it can guarantee it will only send a Request for this destination to the same next hop. The reason for this is that it is possible that the Request will loop back through this same hop from a downstream proxy. he loop will be detected by the next hop if the choice of next hop is fixed, but could loop an arbitrary number of times otherwise. A client requesting with a route HideHeader can only rely on keeping the Request path private if it sends the Request to a trusted proxy. Hiding the route of a SIP Request is of limited value if the Request results in data packets being exchanged directly between the calling and called user agent. The use of HideHeaders is discouraged unless path privacy is truly needed; HideHeaders impose extra processing costs and restrictions for proxies and can cause Requests to generate LOOP_DETECTED Responses that could otherwise be avoided. Version: 0.7

Field Summary

static java.lang.String HIDE_HOP

Hop hide constant static java.lang.String HIDE_ROUTE

Route hide constant static java.lang.String name

Name of HideHeader

Method Summary java.lang.String getHide()

Returns hide value of HideHeader void setHide(java.lang.String hide)

Sets hide value of HideHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail HIDE_ROUTE public static final java.lang.String HIDE_ROUTE Route hide constant

HIDE_HOP public static final java.lang.String HIDE_HOP Hop hide constant

name public static final java.lang.String name Name of HideHeader

Method Detail getHide public java.lang.String getHide() Returns hide value of HideHeader Returns: hide value of HideHeader

setHide public void setHide(java.lang.String hide) throws java.lang.IllegalArgumentException, SipParseException Sets hide value of HideHeader Parameters: hide - hide value of HideHeader Throws: java.lang.IllegalArgumentException - if hide is null SipParseException - if hide is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface MaxForwardsHeader public interface MaxForwardsHeader extends Header This interface represents the Max-Forwards request-header. The MaxForwardsHeader may be used with any SIP method to limit the number of proxies or gateways that can forward the Request to the next downstream server. This can also be useful when the client is attempting to trace a request chain which appears to be failing or looping in mid-chain. The MaxForwards value is an integer indicating the remaining number of times this Request is allowed to be forwarded. Each proxy or gateway recipient of a Request containing a MaxForwardsHeader must check and update its value prior to forwarding the request. If the received value is zero (0), the recipient must not forward the Request. Instead, for OPTIONS and REGISTER Requests, it must respond as the final recipient. For all other methods, the server returns a TOO_MANY_HOPS Response. If the received MaxForwards value is greater than zero, then the forwarded Request must contain an updated MaxForwardsHeader with a value decremented by one (1). Version: 0.7

Field Summary static java.lang.String name

Name of MaxForwardsHeader

Method Summary void decrementMaxForwards()

Decrements the number of max-forwards by one int getMaxForwards()

Gets max-forwards of MaxForwardsHeader void setMaxForwards(int maxForwards)

Sets max-forwards of MaxForwardsHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header

clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of MaxForwardsHeader

Method Detail setMaxForwards public void setMaxForwards(int maxForwards) throws SipParseException Sets max-forwards of MaxForwardsHeader Parameters: maxForwards - number of max-forwards Throws: SipParseException - if maxForwards is not accepted by implementation

decrementMaxForwards public void decrementMaxForwards() throws SipException Decrements the number of max-forwards by one Throws: SipException - if implementation cannot decrement max-fowards i.e. max-forwards has reached zero

getMaxForwards public int getMaxForwards()

Gets max-forwards of MaxForwardsHeader Returns: max-forwards of MaxForwardsHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface NameAddressHeader All Known Subinterfaces: ContactHeader, EndPointHeader, FromHeader, RecordRouteHeader, RouteHeader, ToHeader public interface NameAddressHeader extends Header This interface represents any header that contains a NameAddress value. It is the super-interface of ContactHeader, EndPointHeader, RouteHeader and RecordRouteHeader. Version: 0.7 See Also: ContactHeader, EndPointHeader, RouteHeader, RecordRouteHeader

Method Summary NameAddress getNameAddress()

Gets NameAddress of NameAddressHeader (Returns null if NameAddress does not exist - i.e. void setNameAddress(NameAddress nameAddress)

Sets NameAddress of NameAddressHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Method Detail getNameAddress public NameAddress getNameAddress() Gets NameAddress of NameAddressHeader (Returns null if NameAddress does not exist - i.e. wildcard ContactHeader)

Returns: NameAddress of NameAddressHeader

setNameAddress public void setNameAddress(NameAddress nameAddress) throws java.lang.IllegalArgumentException Sets NameAddress of NameAddressHeader Parameters: nameAddress - NameAddress Throws: java.lang.IllegalArgumentException - if nameAddress is null or not from the same JAIN SIP implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface OptionTagHeader All Known Subinterfaces: ProxyRequireHeader, RequireHeader, UnsupportedHeader public interface OptionTagHeader extends Header This interface represents any header that contains an option tag value. It is the super-interface of ProxyRequireHeader, RequireHeader and UnsupportedHeader. Version: 0.7 See Also: ProxyRequireHeader, RequireHeader, UnsupportedHeader

Method Summary java.lang.String getOptionTag()

Gets option tag of OptionTagHeader void setOptionTag(java.lang.String optionTag)

Sets option tag of OptionTagHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Method Detail getOptionTag public java.lang.String getOptionTag() Gets option tag of OptionTagHeader Returns: option tag of OptionTagHeader

setOptionTag public void setOptionTag(java.lang.String optionTag) throws java.lang.IllegalArgumentException, SipParseException Sets option tag of OptionTagHeader Parameters: optionTag - option tag Throws: java.lang.IllegalArgumentException - if optionTag is null SipParseException - if optionTag is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface OrganizationHeader public interface OrganizationHeader extends Header This interface represents the Organization general-header. The OrganizationHeader conveys the name of the organization to which the entity issuing the Request or Response belongs. It may also be inserted by proxies at the boundary of an organization. It may be used by client software to filter calls. Version: 0.7

Field Summary static java.lang.String name

Name of OrganizationHeader

Method Summary java.lang.String getOrganization()

Gets organization of OrganizationHeader void setOrganization(java.lang.String organization)

Sets organization of OrganizationHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of OrganizationHeader

Method Detail getOrganization public java.lang.String getOrganization() Gets organization of OrganizationHeader Returns: organization of OrganizationHeader

setOrganization public void setOrganization(java.lang.String organization) throws java.lang.IllegalArgumentException, SipParseException Sets organization of OrganizationHeader Parameters: organization - organization Throws: java.lang.IllegalArgumentException - if organization is null SipParseException - if organization is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ParametersHeader All Known Subinterfaces: AcceptHeader, AuthorizationHeader, ContactHeader, ContentTypeHeader, EncryptionHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ResponseKeyHeader, SecurityHeader, ViaHeader, WWWAuthenticateHeader public interface ParametersHeader extends Header, Parameters This interface represents any header that contains parameters. It is a super-interface of ContactHeader, ContentTypeHeader, SecurityHeader and ViaHeader. Version: 0.7 See Also: Parameters, ContactHeader, ContentTypeHeader, SecurityHeader, ViaHeader Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface PriorityHeader public interface PriorityHeader extends Header This interface represents the Priority request-header. The PriorityHeader indicates the urgency of the Request as perceived by the client. The currently defined priority values are: ● PRIORITY_EMERGENCY ● PRIORITY_URGENT ● PRIORITY_NORMAL ● PRIORITY_NON_URGENT It is recommended that the value of PRIORITY_EMERGENCY only be used when life, limb or property are in imminent danger. Version: 0.7

Field Summary static java.lang.String name

Name of PriorityHeader static java.lang.String PRIORITY_EMERGENCY

Emergency priority constant static java.lang.String PRIORITY_NON_URGENT

Non-urgent priority constant static java.lang.String PRIORITY_NORMAL

Normal priority constant static java.lang.String PRIORITY_URGENT

Urgent priority constant

Method Summary java.lang.String getPriority()

Gets priority of PriorityHeader

void setPriority(java.lang.String priority)

Set priority of PriorityHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail PRIORITY_EMERGENCY public static final java.lang.String PRIORITY_EMERGENCY Emergency priority constant

PRIORITY_URGENT public static final java.lang.String PRIORITY_URGENT Urgent priority constant

PRIORITY_NORMAL public static final java.lang.String PRIORITY_NORMAL Normal priority constant

PRIORITY_NON_URGENT public static final java.lang.String PRIORITY_NON_URGENT Non-urgent priority constant

name public static final java.lang.String name Name of PriorityHeader

Method Detail getPriority public java.lang.String getPriority() Gets priority of PriorityHeader Returns: priority of PriorityHeader

setPriority public void setPriority(java.lang.String priority) throws java.lang.IllegalArgumentException, SipParseException Set priority of PriorityHeader Parameters: priority - priority Throws: java.lang.IllegalArgumentException - if priority is null SipParseException - if priority is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ProductHeader All Known Subinterfaces: ServerHeader, UserAgentHeader public interface ProductHeader extends Header This interface represents a header that contains product information. It is the super-interface of ServerHeader and UserAgentHeader. Version: 0.7 See Also: ServerHeader, UserAgentHeader

Method Summary java.util.Iterator getProducts()

Gets products of ProductHeader (Note that the Objects returned by the Iterator are Strings) void setProducts(java.util.List products)

Set products of ProductHeader (Note that the Objects in the List must be Strings)

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Method Detail getProducts public java.util.Iterator getProducts() Gets products of ProductHeader (Note that the Objects returned by the Iterator are Strings) Returns:

products of ProductHeader

setProducts public void setProducts(java.util.List products) throws java.lang.IllegalArgumentException, SipParseException Set products of ProductHeader (Note that the Objects in the List must be Strings) Parameters: products - products Throws: java.lang.IllegalArgumentException - if products is null, empty, or contains any null elements, or contains any non-String objects SipParseException - if any element of products is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ProxyAuthenticateHeader public interface ProxyAuthenticateHeader extends SecurityHeader This interface represents the Proxy-Authenticate response-header. A ProxyAuthenticateHeader must be included as part of a PROXY_AUTHENTICATION_REQUIRED Response. The field value consists of a challenge that indicates the authentication scheme and parameters applicable to the proxy for this RequestURI. Note - Unlike its usage within HTTP, the ProxyAuthenticateHeader must be passed upstream in the Response to the UAC. In SIP, only UAC's can authenticate themselves to proxies. A client should cache the credentials used for a particular proxy server and realm for the next Request to that server. Credentials are, in general, valid for a specific value of the RequestURI at a particular proxy server. If a client contacts a proxy server that has required authentication in the past, but the client does not have credentials for the particular RequestURI, it may attempt to use the most-recently used credential. The server responds with an UNAUTHORIZED Response if the client guessed incorrectly. This suggested caching behavior is motivated by proxies restricting phone calls to authenticated users. It seems likely that in most cases, all destinations require the same password. Note that end-to-end authentication is likely to be destination-specific. Version: 0.7

Field Summary static java.lang.String name

Name of ProxyAuthenticateHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of ProxyAuthenticateHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ProxyAuthorizationHeader public interface ProxyAuthorizationHeader extends SecurityHeader This interface represents the Proxy-Authorization request-header. The ProxyAuthorizationHeader allows the client to identify itself (or its user) to a proxy which requires authentication. The ProxyAuthorizationHeader value consists of credentials containing the authentication information of the user agent for the proxy and/or realm of the resource being requested. Unlike the AuthorizationHeader, the ProxyAuthorizationHeader applies only to the next outbound proxy that demanded authentication using the ProxyAuthenticateHeader. When multiple proxies are used in a chain, the ProxyAuthorizationHeader is consumed by the first outbound proxy that was expecting to receive credentials. A proxy may relay the credentials from the client Request to the next proxy if that is the mechanism by which the proxies cooperatively authenticate a given Request. Version: 0.7

Field Summary static java.lang.String name

Name of ProxyAuthorizationHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of ProxyAuthorizationHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ProxyRequireHeader public interface ProxyRequireHeader extends OptionTagHeader This interface represents the Proxy-Require request-header. The ProxyRequireHeader is used to indicate proxy-sensitive features that must be supported by the proxy. Any ProxyRequireHeader features that are not supported by the proxy must be negatively acknowledged by the proxy to the client if not supported. Proxy servers treat this field identically to the RequireHeader. Version: 0.7 See Also: RequireHeader

Field Summary static java.lang.String name

Name of ProxyRequireHeader

Methods inherited from interface jain.protocol.ip.sip.header.OptionTagHeader getOptionTag, setOptionTag

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of ProxyRequireHeader

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface RecordRouteHeader public interface RecordRouteHeader extends NameAddressHeader This interface represents the Record-Route general-header. The RecordRouteHeader is added to a Request by any proxy that insists on being in the path of subsequent Requests for the same call leg. It contains a globally reachable RequestURI that identifies the proxy server. Each proxy server adds its RequestURI to the beginning of the list. The server copies the RecordRouteHeader unchanged into the Response. (RecordRouteHeader is only relevant for SUCCESS Responses.) The calling user agent client copies the RecordRouteHeaders into RouteHeaders of subsequent Requests within the same call leg, reversing the order, so that the first entry is closest to the user agent client. If the Response contained a ContactHeader field, the calling user agent adds its content as the last RouteHeader. Unless this would cause a loop, any client must send any subsequent Requests for this call leg to the RequestURI in the first RouteHeader and remove that entry. The calling user agent must not use the RecordRouteHeaders in Requests that contain RouteHeaders. Some proxies, such as those controlling firewalls or in an automatic call distribution (ACD) system, need to maintain call state and thus need to receive any BYE and ACK Requests for the call. Proxy servers should use the SipURL maddr in the NameAddress containing their address to ensure that subsequent Requests are guaranteed to reach exactly the same server. Version: 0.7 See Also: RouteHeader

Field Summary static java.lang.String name

Name of RecordRouteHeader

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of RecordRouteHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface RequireHeader public interface RequireHeader extends OptionTagHeader This interface representshe Require request-header. The RequireHeader is used by clients to tell user agent servers about options that the client expects the server to support in order to properly process the Request. If a server does not understand the option, it must respond by returning a BAD_EXTENSION Response and list those options it does not understand in the UnsupportedHeader. This is to make sure that the client-server interaction will proceed without delay when all options are understood by both sides, and only slow down if options are not understood. For a well-matched client-server pair, the interaction proceeds quickly, saving a round-trip often required by negotiation mechanisms. In addition, it also removes ambiguity when the client requires features that the server does not understand. Some features, such as call handling fields, are only of interest to end systems. Proxy and redirect servers must ignore features that are not understood. If a particular extension requires that intermediate devices support it, the extension must be tagged in the ProxyRequireHeader as well. Version: 0.7 See Also: ProxyRequireHeader

Field Summary static java.lang.String name

Name of RequireHeader

Methods inherited from interface jain.protocol.ip.sip.header.OptionTagHeader getOptionTag, setOptionTag

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of RequireHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ResponseKeyHeader public interface ResponseKeyHeader extends SecurityHeader This interface represents the Response-Key request-header. The ResponseKeyHeader can be used by a client to request the key that the called user agent should use to encrypt the Response with. The scheme gives the type of encryption to be used for the Response. If the client insists that the server return an encrypted Response, it includes a RequireHeader with an option tag of "org.ietf.sip.encrypt-response" in its Request. If the server cannot encrypt for whatever reason, it must follow normal RequireHeader procedures and return a BAD_EXTENSION Response. If this RequireHeader is not present, a server should still encrypt if it can. Version: 0.7 See Also: RequireHeader

Field Summary static java.lang.String name

Name of ResponseKeyHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of ResponseKeyHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface RetryAfterHeader public interface RetryAfterHeader extends ExpiresHeader This interface represents the Retry-After general-header. The RetryAfterHeader can be used with a SERVICE_UNAVAILABLE Response to indicate how long the service is expected to be unavailable to the requesting client and with a NOT_FOUND, BUSY, or DECLINE Response to indicate when the called party anticipates being available again. The value of this field can be either a date or an integer number of seconds (in decimal) after the time of the Response. A REGISTER Request may include a RetryAfterHeader when deleting registrations with a wildcard ContactHeader. The value then indicates when the user might again be reachable. The registrar may then include this information in Responses to future calls. An optional comment can be used to indicate additional information about the time of callback. An optional duration indicates how long the called party will be reachable starting at the initial time of availability. If no duration is given, the service is assumed to be available indefinitely. Version: 0.7

Field Summary static java.lang.String name

Name of RetryAfterHeader

Fields inherited from interface jain.protocol.ip.sip.header.ExpiresHeader name

Fields inherited from interface jain.protocol.ip.sip.header.DateHeader name

Method Summary

java.lang.String getComment()

Gets comment of RetryAfterHeader (Returns null if comment does not exist) long getDuration()

Gets duration of RetryAfterHeader (Returns negative long if duration does not exist) boolean hasComment()

Gets boolean value to indicate if RetryAfterHeader has comment boolean hasDuration()

Gets boolean value to indicate if RetryAfterHeader has duration void removeComment()

Removes comment from RetryAfterHeader (if it exists) void removeDuration()

Removes duration from RetryAfterHeader (if it exists) void setComment(java.lang.String comment)

Sets comment of RetryAfterHeader void setDuration(long duration)

Sets duration of RetryAfterHeader

Methods inherited from interface jain.protocol.ip.sip.header.ExpiresHeader getDeltaSeconds, isDate, setDeltaSeconds

Methods inherited from interface jain.protocol.ip.sip.header.DateHeader getDate, setDate, setDate

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of RetryAfterHeader

Method Detail getComment public java.lang.String getComment() Gets comment of RetryAfterHeader (Returns null if comment does not exist) Returns: comment of RetryAfterHeader

hasComment public boolean hasComment() Gets boolean value to indicate if RetryAfterHeader has comment Returns: boolean value to indicate if RetryAfterHeader has comment

removeComment public void removeComment() Removes comment from RetryAfterHeader (if it exists)

getDuration public long getDuration() Gets duration of RetryAfterHeader (Returns negative long if duration does not exist) Returns: duration of RetryAfterHeader

hasDuration public boolean hasDuration() Gets boolean value to indicate if RetryAfterHeader has duration Returns: boolean value to indicate if RetryAfterHeader has duration

removeDuration public void removeDuration() Removes duration from RetryAfterHeader (if it exists)

setComment public void setComment(java.lang.String comment) throws java.lang.IllegalArgumentException, SipParseException Sets comment of RetryAfterHeader Parameters: comment - comment Throws: java.lang.IllegalArgumentException - if comment is null SipParseException - if comment is not accepted by implementation

setDuration public void setDuration(long duration) throws SipParseException Sets duration of RetryAfterHeader Parameters: duration - duration Throws: SipParseException - if duration is not accepted by implementation

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface RouteHeader public interface RouteHeader extends NameAddressHeader This interface represents the Route request-header. RouteHeaders determine the route taken by a Request. Each host removes the first entry and then proxies the Request to the host listed in that entry, also using it as the RequestURI. The operation is further described in RecordRouteHeader. Version: 0.7 See Also: RecordRouteHeader

Field Summary static java.lang.String name

Name of RouteHeader

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of RouteHeader If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface SecurityHeader All Known Subinterfaces: AuthorizationHeader, EncryptionHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ResponseKeyHeader, WWWAuthenticateHeader public interface SecurityHeader extends ParametersHeader This interface represents headers used in SIP security. It is comprised of a security scheme and associated parameters. It is the super-interface of AuthorizationHeader, EncryptionHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ResponseKeyHeader and WWWAuthenticateHeader. Version: 0.7 See Also: AuthorizationHeader, EncryptionHeader, ProxyAuthenticateHeader, ProxyAuthorizationHeader, ResponseKeyHeader, WWWAuthenticateHeader

Method Summary java.lang.String getScheme()

Method used to get the scheme void setScheme(java.lang.String scheme)

Method used to set the scheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Method Detail setScheme public void setScheme(java.lang.String scheme) throws java.lang.IllegalArgumentException, SipParseException Method used to set the scheme Parameters: String - the scheme Throws: java.lang.IllegalArgumentException - if scheme is null SipParseException - if scheme is not accepted by implementation

getScheme public java.lang.String getScheme() Method used to get the scheme Returns: the scheme If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ServerHeader public interface ServerHeader extends ProductHeader This interface represents the Server response-header. A ServerHeader contains information about the software used by the server to handle the Request. A Response can contain multiple ServerHeaders identifying the server and any significant subproducts. The ServerHeaders are listed in order of their significance for identifying the application. If the Response is being forwarded through a proxy, the proxy application must not modify the ServerHeaders. Instead, it should include a ViaHeader Note: Revealing the specific software version of the server may allow the server machine to become more vulnerable to attacks against software that is known to contain security holes. Server implementers are encouraged to make this field a configurable option. Version: 0.7 See Also: ViaHeader

Field Summary static java.lang.String name

Name of ServerHeader

Methods inherited from interface jain.protocol.ip.sip.header.ProductHeader getProducts, setProducts

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of ServerHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface SubjectHeader public interface SubjectHeader extends Header This interface represents the Subject request-header. The SubjectHeader is intended to provide a summary, or to indicate the nature, of the call, allowing call filtering without having to parse the session description. (Also, the session description does not have to use the same subject indication as the invitation.) Version: 0.7

Field Summary static java.lang.String name

Name of SubjectHeader

Method Summary java.lang.String getSubject()

Gets subject of SubjectHeader void setSubject(java.lang.String subject)

Sets subject of SubjectHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of SubjectHeader

Method Detail getSubject public java.lang.String getSubject() Gets subject of SubjectHeader Returns: subject of SubjectHeader

setSubject public void setSubject(java.lang.String subject) throws java.lang.IllegalArgumentException, SipParseException Sets subject of SubjectHeader Parameters: subject - subject Throws: java.lang.IllegalArgumentException - if subject is null SipParseException - if subject is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface TimeStampHeader public interface TimeStampHeader extends Header This interface represents the Timestamp general-header. The TimeStampHeader describes when the client sent the Request to the server. The value of the timestamp is of significance only to the client and it may use any timescale. The server must echo the exact same value and may, if it has accurate information about this, add a floating point number indicating the number of seconds that have elapsed since it has received the Request. The TimestampHeader is used by the client to compute the round-trip time to the server so that it can adjust the timeout value for retransmissions. Version: 0.7

Field Summary static java.lang.String name

Name of TimeStampHeader

Method Summary float getDelay()

Gets delay of TimeStampHeader (Returns neagative float if delay does not exist) float getTimeStamp()

Gets timestamp of TimeStampHeader boolean hasDelay()

Gets boolean value to indicate if TimeStampHeader has delay void removeDelay()

Removes delay from TimeStampHeader (if it exists) void setDelay(float delay)

Sets delay of TimeStampHeader void setTimeStamp(float timeStamp)

Sets timestamp of TimeStampHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of TimeStampHeader

Method Detail getTimeStamp public float getTimeStamp() Gets timestamp of TimeStampHeader Returns: timestamp of TimeStampHeader

getDelay public float getDelay() Gets delay of TimeStampHeader (Returns neagative float if delay does not exist) Returns: delay of TimeStampHeader

hasDelay public boolean hasDelay() Gets boolean value to indicate if TimeStampHeader has delay Returns: boolean value to indicate if TimeStampHeader has delay

setTimeStamp public void setTimeStamp(float timeStamp) throws SipParseException Sets timestamp of TimeStampHeader Parameters: timeStamp - timestamp Throws: SipParseException - if timeStamp is not accepted by implementation

setDelay public void setDelay(float delay) throws SipParseException Sets delay of TimeStampHeader Parameters: delay - delay Throws: SipParseException - if delay is not accepted by implementation

removeDelay public void removeDelay() Removes delay from TimeStampHeader (if it exists) If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ToHeader public interface ToHeader extends EndPointHeader This interface represents the To general-header. The ToHeader specifies the recipient of the Request, with the same NameAddress rules as the FromHeader. Requests and Responses must contain a ToHeader, indicating the desired recipient of the Request using the NameAddress. The optional display-name of the NameAddress is meant to be rendered by a human-user interface. The UAS or redirect server copies the ToHeader into its Response, and must add a tag if the Request contained more than one ViaHeader. If there was more than one ViaHeader, the Request was handled by at least one proxy server. Since the receiver cannot know whether any of the proxy servers forked the Request, it is safest to assume that they might have. The SipURL of the NameAddress must not contain the transport, maddr, ttl, or headers elements. A server that receives a SipURL with these elements removes them before further processing. The tag serves as a general mechanism to distinguish multiple instances of a user identified by a single SipURL. As proxies can fork Requests, the same Request can reach multiple instances of a user (mobile and home phones, for example). As each can respond, there needs to be a means to distinguish the Responses from each other at the caller. The situation also arises with multicast Requests. The tag in the ToHeader serves to distinguish Responses at the UAC. It must be placed in the ToHeader of the Response by each instance when there is a possibility that the Request was forked at an intermediate proxy. The tag must be added by UAS, registrars and redirect servers, but must not be inserted into Responses forwarded upstream by proxies. The tag is added for all definitive Responses for all Requests, and may be added for informational Responses from a UAS or redirect server. All subsequent transactions between two entities must include the tag. The tag in ToHeaders is ignored when matching Responses to Requests that did not contain a tag in their ToHeader. A SIP server returns a BAD_REQUEST Response if it receives a Request with a ToHeader containing a URI with a scheme it does not recognize. CallIdHeader, ToHeader and FromHeader are needed to identify a call leg. The distinction between call and call leg matters in calls with multiple Responses from a forked Request. The tag is added to the ToHeader in the Response to allow forking of future Requests for the same call by proxies, while addressing only one of the possibly several responding user agent servers. It also allows several instances of the callee to send Requests that can be distinguished. Version: 0.7

Field Summary static java.lang.String name

Name of ToHeader

Methods inherited from interface jain.protocol.ip.sip.header.EndPointHeader getTag, hasTag, removeTag, setTag

Methods inherited from interface jain.protocol.ip.sip.header.NameAddressHeader getNameAddress, setNameAddress

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of ToHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface UnsupportedHeader public interface UnsupportedHeader extends OptionTagHeader This interface represents the Unsupported response-header. UnsupportedHeaders list the features not supported by the server. See RequireHeader for more information. Version: 0.7 See Also: RequireHeader

Field Summary static java.lang.String name

Name of UnsupportedHeader

Methods inherited from interface jain.protocol.ip.sip.header.OptionTagHeader getOptionTag, setOptionTag

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of UnsupportedHeader If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface UserAgentHeader public interface UserAgentHeader extends ProductHeader This interface represents the User-Agent general-header. A UserAgentHeader contains information about the user agent originating the Request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring Responses to avoid particular user agent limitations. User agents should include this header with Requests. Requests can contain multiple UserAgentHeaders identifying the agent and any subproducts which form a significant part of the user agent. By convention, the UserAgentHeaders are listed in order of their significance for identifying the application. Similar security considerations apply for in ServerHeaders. Version: 0.7 See Also: ServerHeader

Field Summary static java.lang.String name

Name of UserAgentHeader

Methods inherited from interface jain.protocol.ip.sip.header.ProductHeader getProducts, setProducts

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail

name public static final java.lang.String name Name of UserAgentHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface ViaHeader public interface ViaHeader extends ParametersHeader This interface represents the Via general-header. ViaHeaders indicates the path taken by the Request so far. This prevents Request looping and ensures Responses take the same path as the Requests, which assists in firewall traversal and other unusual routing situations. Requests The client originating the Request must insert into the Request a ViaHeader containing its host name or network address and, if not the default port number, the port number at which it wishes to receive Responses. (Note that this port number can differ from the UDP source port number of the Request.) A fully-qualified domain name is recommended. Each subsequent proxy server that sends the Request onwards must add its own additional ViaHeader before any existing ViaHeaders. A proxy that receives a redirection Response and then searches recursively, must use the same ViaHeaders as on the original proxied Request. A proxy should check the top-most ViaHeader to ensure that it contains the sender's correct network address, as seen from that proxy. If the sender's address is incorrect, the proxy must add an additional received attribute. A host behind a network address translator (NAT) or firewall may not be able to insert a network address into the ViaHeader that can be reached by the next hop beyond the NAT. Use of the received attribute allows SIP Requests to traverse NAT's which only modify the source IP address. NAT's which modify port numbers, called Network Address Port Translator's (NAPT) will not properly pass SIP when transported on UDP, in which case an application layer gateway is required. When run over TCP, SIP stands a better chance of traversing NAT's, since its behavior is similar to HTTP in this case (but of course on different ports). A proxy sending a Request to a multicast address must add the maddr parameter to its ViaHeader, and should add the ttl parameter. If a server receives a Request which contained an maddr parameter in the topmost ViaHeader, it should send the Response to the multicast address listed in the maddr parameter. If a proxy server receives a Request which contains its own address in a ViaHeader, it must respond with a LOOP_DETECTED Response. A proxy server must not forward a Request to a multicast group which already appears in any of the ViaHeaders. This prevents a malfunctioning proxy server from causing loops. Also, it cannot be guaranteed that a proxy server can always detect that the address returned by a location service refers to a host listed in the ViaHeader list, as a single host may have aliases or several network interfaces. Receiver-tagged Via Headers

Normally, every host that sends or forwards a Request adds a ViaHeader indicating the path traversed. However, it is possible that Network Address Translators (NATs) changes the source address and port of the Request (e.g., from net-10 to a globally routable address), in which case the Via header field cannot be relied on to route replies. To prevent this, a proxy should check the top-most ViaHeader to ensure that it contains the sender's correct network address, as seen from that proxy. If the sender's address is incorrect, the proxy must add a received parameter to the ViaHeader inserted by the previous hop. Such a modified ViaHeader is known as a receiver-tagged ViaHeader. Responses ViaHeaders in Responses are processed by a proxy or UAC according to the following rules: ● The first ViaHeader should indicate the proxy or client processing this Response. If it does not, discard the Response. Otherwise, remove this ViaHeader. ● If there is no second ViaHeader, this Response is destined for this client. Otherwise, the processing depends on whether the ViaHeader contains a maddr parameter or is a receiver-tagged field. ● If the second ViaHeader contains a maddr parameter, send the Response to the multicast address listed there, using the port indicated in "sent-by", or port 5060 if none is present. The Response should be sent using the TTL indicated in the ttl parameter, or with a TTL of 1 if that parameter is not present. For robustness, Responses must be sent to the address indicated in the maddr parameter even if it is not a multicast address. ● If the second ViaHeader does not contain a maddr parameter and is a receiver-tagged ViaHeader , send the Response to the address in the received parameter, using the port indicated in the port value, or using port 5060 if none is present. ● If neither of the previous cases apply, send the Response to the address indicated by the host value in the second ViaHeader. User Agent and Redirect Servers A UAS or redirect server sends a Response based on one of the following rules: ● If the first ViaHeader in the Request contains a maddr parameter, send the Response to the multicast address listed there, using the port indicated, or port 5060 if none is present. The Response should be sent using the TTL indicated in the ttl parameter, or with a TTL of 1 if that parameter is not present. For robustness, Responses must be sent to the address indicated in the maddr parameter even if it is not a multicast address. ● If the address in the first ViaHeader differs from the source address of the packet, send the Response to the actual packet source address, similar to the treatment for receiver-tagged ViaHeaders. ● If neither of these conditions is true, send the Response to the address contained in the host value. If the Request was sent using TCP, use the existing TCP connection if available. ViaHeader Parameters The defaults for protocol-name and transport are "SIP" and "UDP", respectively. The maddr parameter, designating the multicast address, and the ttl parameter, designating the time-to-live (TTL) value, are included only if the Request was sent via multicast. The received parameter is added only for receiver-added ViaHeaders For reasons of privacy, a client or proxy may wish to hide its ViaHeader information by encrypting it. The hidden parameter is included if this ViaHeader was hidden by the

upstream proxy. Note that privacy of the proxy relies on the cooperation of the next hop, as the next-hop proxy will, by necessity, know the IP address and port number of the source host. The branch parameter is included by every forking proxy. The token must be unique for each distinct Request generated when a proxy forks. CANCEL Requests must have the same branch value as the corresponding forked Request. When a Response arrives at the proxy it can use the branch value to figure out which branch the Response corresponds to. A proxy which generates a single Request (non- forking) may also insert the branch parameter. The identifier has to be unique only within a set of isomorphic Requests. Version: 0.7

Field Summary static java.lang.String name

Name of ViaHeader static java.lang.String TCP

TCP constant for ViaHeader static java.lang.String UDP

UDP constant for ViaHeader

Method Summary java.lang.String getBranch()

Gets branch of ViaHeader (Returns null if branch does not exist) java.lang.String getComment()

Gets comment of ViaHeader (Returns null if comment does not exist) java.lang.String getHost()

Gets host of ViaHeader java.lang.String getMAddr()

Gets MAddr of ViaHeader (Returns null if MAddr does not exist) int getPort()

Gets port of ViaHeader (Returns negative int if port does not exist) java.lang.String getProtocolVersion()

Gets protocol version of ViaHeader java.lang.String getReceived()

Gets received of ViaHeader (Returns null if received does not exist)

java.lang.String getTransport()

Gets transport of ViaHeader int getTTL()

Gets TTL of ViaHeader (Returns negative int if TTL does not exist) boolean hasBranch()

Gets boolean value to indicate if ViaHeader has branch boolean hasComment()

Gets boolean value to indicate if ViaHeader has comment boolean hasPort()

Returns boolean value indicating if ViaHeader has port boolean hasReceived()

Gets boolean value to indicate if ViaHeader has received boolean hasTTL()

Gets boolean value to indicate if ViaHeader has TTL boolean isHidden()

Returns boolean value indicating if ViaHeader is hidden void removeBranch()

Removes branch from ViaHeader (if it exists) void removeComment()

Removes comment from ViaHeader (if it exists) void removeMAddr()

Removes MAddr from ViaHeader (if it exists) void removePort()

Removes port from ViaHeader (if it exists) void removeReceived()

Removes received from ViaHeader (if it exists) void removeTTL()

Removes TTL from ViaHeader (if it exists) void setBranch(java.lang.String branch)

Sets branch of ViaHeader void setComment(java.lang.String comment)

Sets comment of ViaHeader void setHidden(boolean hidden)

Sets whether ViaHeader is hidden or not

void setHost(java.net.InetAddress host)

Sets host of ViaHeader void setHost(java.lang.String host)

Sets host of ViaHeader void setMAddr(java.net.InetAddress mAddr)

Sets MAddr of ViaHeader void setMAddr(java.lang.String mAddr)

Sets MAddr of ViaHeader void setPort(int port)

Sets port of ViaHeader void setProtocolVersion(java.lang.String protocolVersion)

Sets protocol version of ViaHeader void setReceived(java.net.InetAddress received)

Sets received of ViaHeader void setReceived(java.lang.String received)

Sets received of ViaHeader void setTransport(java.lang.String transport)

Sets transport of ViaHeader void setTTL(int ttl)

Sets TTL of ViaHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail

name public static final java.lang.String name Name of ViaHeader

TCP public static final java.lang.String TCP TCP constant for ViaHeader

UDP public static final java.lang.String UDP UDP constant for ViaHeader

Method Detail isHidden public boolean isHidden() Returns boolean value indicating if ViaHeader is hidden Returns: boolean value indicating if ViaHeader is hidden

setHidden public void setHidden(boolean hidden) Sets whether ViaHeader is hidden or not Parameters: hidden - whether ViaHeader is hidden or not

hasPort public boolean hasPort() Returns boolean value indicating if ViaHeader has port Returns: boolean value indicating if ViaHeader has port

getPort public int getPort() Gets port of ViaHeader (Returns negative int if port does not exist) Returns: port of ViaHeader

setPort public void setPort(int port) throws SipParseException Sets port of ViaHeader Parameters: port - port Throws: SipParseException - if port is not accepted by implementation

removePort public void removePort() Removes port from ViaHeader (if it exists)

getProtocolVersion public java.lang.String getProtocolVersion() Gets protocol version of ViaHeader

Returns: protocol version of ViaHeader

setProtocolVersion public void setProtocolVersion(java.lang.String protocolVersion) throws java.lang.IllegalArgumentException, SipParseException Sets protocol version of ViaHeader Parameters: protocolVersion - protocol version Throws: java.lang.IllegalArgumentException - if protocolVersion is null SipParseException - if protocolVersion is not accepted by implementation

getTransport public java.lang.String getTransport() Gets transport of ViaHeader Returns: transport of ViaHeader

setTransport public void setTransport(java.lang.String transport) throws java.lang.IllegalArgumentException, SipParseException Sets transport of ViaHeader Parameters: transport - transport Throws: java.lang.IllegalArgumentException - if transport is null SipParseException - if transport is not accepted by implementation

getHost public java.lang.String getHost() Gets host of ViaHeader Returns: host of ViaHeader

setHost public void setHost(java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Sets host of ViaHeader Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

setHost public void setHost(java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException Sets host of ViaHeader Parameters: host - host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

getComment public java.lang.String getComment()

Gets comment of ViaHeader (Returns null if comment does not exist) Returns: comment of ViaHeader

hasComment public boolean hasComment() Gets boolean value to indicate if ViaHeader has comment Returns: boolean value to indicate if ViaHeader has comment

setComment public void setComment(java.lang.String comment) throws java.lang.IllegalArgumentException, SipParseException Sets comment of ViaHeader Parameters: comment - comment Throws: java.lang.IllegalArgumentException - if comment is null SipParseException - if comment is not accepted by implementation

removeComment public void removeComment() Removes comment from ViaHeader (if it exists)

setTTL public void setTTL(int ttl) throws SipParseException Sets TTL of ViaHeader Parameters:

ttl - TTL Throws: SipParseException - if ttl is not accepted by implementation

removeTTL public void removeTTL() Removes TTL from ViaHeader (if it exists)

getTTL public int getTTL() Gets TTL of ViaHeader (Returns negative int if TTL does not exist) Returns: TTL of ViaHeader

hasTTL public boolean hasTTL() Gets boolean value to indicate if ViaHeader has TTL Returns: boolean value to indicate if ViaHeader has TTL

setMAddr public void setMAddr(java.lang.String mAddr) throws java.lang.IllegalArgumentException, SipParseException Sets MAddr of ViaHeader Parameters: mAddr - MAddr Throws: java.lang.IllegalArgumentException - if mAddr is null SipParseException - if mAddr is not accepted by implementation

setMAddr public void setMAddr(java.net.InetAddress mAddr) throws java.lang.IllegalArgumentException, SipParseException Sets MAddr of ViaHeader Parameters: mAddr - MAddr Throws: java.lang.IllegalArgumentException - if mAddr is null SipParseException - if mAddr is not accepted by implementation

removeMAddr public void removeMAddr() Removes MAddr from ViaHeader (if it exists)

getMAddr public java.lang.String getMAddr() Gets MAddr of ViaHeader (Returns null if MAddr does not exist) Returns: MAddr of ViaHeader

setReceived public void setReceived(java.lang.String received) throws java.lang.IllegalArgumentException, SipParseException Sets received of ViaHeader Parameters: received - received Throws:

java.lang.IllegalArgumentException - if received is null SipParseException - if received is not accepted by implementation

setReceived public void setReceived(java.net.InetAddress received) throws java.lang.IllegalArgumentException, SipParseException Sets received of ViaHeader Parameters: received - received Throws: java.lang.IllegalArgumentException - if received is null SipParseException - if received is not accepted by implementation

removeReceived public void removeReceived() Removes received from ViaHeader (if it exists)

getReceived public java.lang.String getReceived() Gets received of ViaHeader (Returns null if received does not exist) Returns: received of ViaHeader

hasReceived public boolean hasReceived() Gets boolean value to indicate if ViaHeader has received Returns: boolean value to indicate if ViaHeader has received

setBranch public void setBranch(java.lang.String branch) throws java.lang.IllegalArgumentException, SipParseException Sets branch of ViaHeader Parameters: branch - branch Throws: java.lang.IllegalArgumentException - if branch is null SipParseException - if branch is not accepted by implementation

removeBranch public void removeBranch() Removes branch from ViaHeader (if it exists)

getBranch public java.lang.String getBranch() Gets branch of ViaHeader (Returns null if branch does not exist) Returns: branch of ViaHeader

hasBranch public boolean hasBranch() Gets boolean value to indicate if ViaHeader has branch Returns: boolean value to indicate if ViaHeader has branch If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface WarningHeader public interface WarningHeader extends Header This interface represents the Warning response-header. WarningHeader is used to carry additional information about the status of a Response. WarningHeaders are sent with Responses and a Response may carry more than one WarningHeader. The text should be in a natural language that is most likely to be intelligible to the human user receiving the Response. This decision can be based on any available knowledge, such as the location of the cache or user, the AcceptLanguageHeader in a Request, or the ContentLanguageHeader in a Response. Any server may add WarningHeaders to a Response. Proxy servers must place additional WarningHeaders before any AuthorizationHeaders. Within that constraint, WarningHeaders must be added after any existing WarningHeaders not covered by a signature. A proxy server must not delete any WarningHeader that it received with a Response. When multiple WarningHeaders are attached to a Response, the user agent should display as many of them as possible, in the order that they appear in the Response. If it is not possible to display all of the warnings, the user agent first displays warnings that appear early in the Response. The warning code consists of three digits. A first digit of "3" indicates warnings specific to SIP (1xx and 2xx have been taken by HTTP/1.1). This is a list of the currently-defined "warn-code"s, each with a recommended warning text in English, and a description of its meaning. Note that these warnings describe failures induced by the session description. Warning codes 300 through 329 are reserved for indicating problems with keywords in the session description, 330 through 339 are warnings related to basic network services requested in the session description, 370 through 379 are warnings related to quantitative QoS parameters requested in the session description, and 390 through 399 are miscellaneous warnings that do not fall into one of the above categories. Warning code constants are defined in this interface. Version: 0.7

Field Summary static int ATTRIBUTE_NOT_UNDERSTOOD

One or more of the media attributes in the session description are not supported.

static int INCOMPATIBLE_BANDWIDTH_UNITS

One or more bandwidth measurement units contained in the session description were not understood. static int INCOMPATIBLE_MEDIA_FORMAT

One or more media formats contained in the session description are not available. static int INCOMPATIBLE_NETWORK_ADDRESS_FORMATS

One or more network address formats contained in the session description are not available. static int INCOMPATIBLE_NETWORK_PROTOCOL

One or more network protocols contained in the session description are not available. static int INCOMPATIBLE_TRANSPORT_PROTOCOL

One or more transport protocols described in the session description are not available. static int INSUFFICIENT_BANDWIDTH

The bandwidth specified in the session description or defined by the media exceeds that known to be available. static int MEDIA_TYPE_NOT_AVAILABLE

One or more media types contained in the session description are not available. static int MISCELLANEOUS_WARNING

The warning text can include arbitrary information to be presented to a human user, or logged. static int MULTICAST_NOT_AVAILABLE

The site where the user is located does not support multicast. static java.lang.String name

Name of WarningHeader static int SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD

A parameter other than those listed above was not understood. static int UNICAST_NOT_AVAILABLE

The site where the user is located does not support unicast communication (usually due to the presence of a firewall).

Method Summary

int getCode()

Gets code of WarningHeader java.lang.String getHost()

Gets agent host of WarningHeader int getPort()

Gets agent port of WarningHeader (Returns negative int if port does not exist) java.lang.String getText()

Gets text of WarningHeader boolean hasPort()

Returns boolean value indicating if WarningHeader has port void removePort()

Removes port from WarningHeader (if it exists) void setCode(int code)

Sets code of WarningHeader void setHost(java.net.InetAddress host)

Sets agent host of WarningHeader void setHost(java.lang.String host)

Sets agent host of WarningHeader void setPort(int port)

Sets agent port of WarningHeader void setText(java.lang.String text)

Sets text of WarningHeader

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Field Detail name public static final java.lang.String name Name of WarningHeader

INCOMPATIBLE_NETWORK_PROTOCOL public static final int INCOMPATIBLE_NETWORK_PROTOCOL One or more network protocols contained in the session description are not available.

INCOMPATIBLE_NETWORK_ADDRESS_FORMATS public static final int INCOMPATIBLE_NETWORK_ADDRESS_FORMATS One or more network address formats contained in the session description are not available.

INCOMPATIBLE_TRANSPORT_PROTOCOL public static final int INCOMPATIBLE_TRANSPORT_PROTOCOL One or more transport protocols described in the session description are not available.

INCOMPATIBLE_BANDWIDTH_UNITS public static final int INCOMPATIBLE_BANDWIDTH_UNITS One or more bandwidth measurement units contained in the session description were not understood.

MEDIA_TYPE_NOT_AVAILABLE public static final int MEDIA_TYPE_NOT_AVAILABLE One or more media types contained in the session description are not available.

INCOMPATIBLE_MEDIA_FORMAT public static final int INCOMPATIBLE_MEDIA_FORMAT One or more media formats contained in the session description are not available.

ATTRIBUTE_NOT_UNDERSTOOD public static final int ATTRIBUTE_NOT_UNDERSTOOD One or more of the media attributes in the session description are not supported.

SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD public static final int SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD A parameter other than those listed above was not understood.

MULTICAST_NOT_AVAILABLE public static final int MULTICAST_NOT_AVAILABLE The site where the user is located does not support multicast.

UNICAST_NOT_AVAILABLE public static final int UNICAST_NOT_AVAILABLE The site where the user is located does not support unicast communication (usually due to the presence of a firewall).

INSUFFICIENT_BANDWIDTH public static final int INSUFFICIENT_BANDWIDTH The bandwidth specified in the session description or defined by the media exceeds that known to be available.

MISCELLANEOUS_WARNING public static final int MISCELLANEOUS_WARNING The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning MUST NOT take any automated action.

Method Detail getCode public int getCode() Gets code of WarningHeader Returns: code of WarningHeader

getHost public java.lang.String getHost() Gets agent host of WarningHeader Returns: agent host of WarningHeader

getPort public int getPort() Gets agent port of WarningHeader (Returns negative int if port does not exist) Returns: agent port of WarningHeader

hasPort public boolean hasPort() Returns boolean value indicating if WarningHeader has port Returns: boolean value indicating if WarningHeader has port

getText public java.lang.String getText() Gets text of WarningHeader Returns: text of WarningHeadert

setCode public void setCode(int code) throws SipParseException Sets code of WarningHeader Parameters: code - code Throws: SipParseException - if code is not accepted by implementation

setHost public void setHost(java.lang.String host) throws java.lang.IllegalArgumentException, SipParseException Sets agent host of WarningHeader Parameters: host - agent host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

setHost public void setHost(java.net.InetAddress host) throws java.lang.IllegalArgumentException, SipParseException

Sets agent host of WarningHeader Parameters: host - agent host Throws: java.lang.IllegalArgumentException - if host is null SipParseException - if host is not accepted by implementation

setPort public void setPort(int port) throws SipParseException Sets agent port of WarningHeader Parameters: port - agent port Throws: SipParseException - if agentPort is not accepted by implementation

removePort public void removePort() Removes port from WarningHeader (if it exists)

setText public void setText(java.lang.String text) throws java.lang.IllegalArgumentException, SipParseException Sets text of WarningHeader Parameters: text - text Throws: java.lang.IllegalArgumentException - if text is null SipParseException - if text is not accepted by implementation If you have any comments or queries, please mail them to [email protected]

Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Interface WWWAuthenticateHeader public interface WWWAuthenticateHeader extends SecurityHeader This interface represents the WWW-Authenticate response-header. At least one WWWAuthenticateHeader must be included in UNAUTHORIZED Responses. The header value consists of a challenge that indicates the authentication scheme(s) and parameters applicable to the RequestURI. Version: 0.7 See Also: AuthorizationHeader

Field Summary static java.lang.String name

Name of WWWAuthenticateHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail

name public static final java.lang.String name Name of WWWAuthenticateHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header

Class HeaderParseException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--jain.protocol.ip.sip.SipException | +--jain.protocol.ip.sip.SipParseException | +--jain.protocol.ip.sip.header.HeaderParseException public class HeaderParseException extends SipParseException The HeaderParseException is thrown by an implementation that cannot parse a header value when an application asks a Message for an API-defined Header object (e.g. ContentTypeHeader). The application may wish to view the unparsable header's value as a String (and it may not know the header name if it simply called Message's getHeaders() method) so the HeaderParseException contains a generic Header object that can be accessed with the getHeader() method. Note that this exception will never be thrown when an application asks for a FromHeader, ToHeader, CallIdHeader or CSeqHeader - if a received Message does not contain these four headers it must be handled appropriately by an implementation. Also note that this exception will never be thrown by an eager-parsing implementation, because it will have fully parsed all Messages passed to an application and handled all others itself. Version: 0.7 See Also: Serialized Form

Constructor Summary HeaderParseException(Header header) Constructs new HeaderParseException based on specified Header HeaderParseException(java.lang.String message, Header header) Constructs new HeaderParseException based on specified Header and a message

Method Summary

Header getHeader()

Gets Header of this HeaderParseException

Methods inherited from class jain.protocol.ip.sip.SipParseException getUnparsable

Methods inherited from class java.lang.Throwable fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail HeaderParseException public HeaderParseException(Header header) Constructs new HeaderParseException based on specified Header Parameters: header - Header to base HeaderParseException on

HeaderParseException public HeaderParseException(java.lang.String message, Header header) Constructs new HeaderParseException based on specified Header and a message Parameters: msg - message of this HeaderParseException. header - Header to base HeaderParseException on

Method Detail

getHeader public Header getHeader() Gets Header of this HeaderParseException Returns: Header of this HeaderParseException If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.header Interfaces AcceptEncodingHeader AcceptHeader AcceptLanguageHeader AllowHeader AuthorizationHeader CallIdHeader ContactHeader ContentEncodingHeader ContentLengthHeader ContentTypeHeader CSeqHeader DateHeader EncodingHeader EncryptionHeader EndPointHeader ExpiresHeader FromHeader Header HeaderFactory HeaderIterator HideHeader MaxForwardsHeader NameAddressHeader OptionTagHeader OrganizationHeader ParametersHeader PriorityHeader ProductHeader ProxyAuthenticateHeader ProxyAuthorizationHeader ProxyRequireHeader RecordRouteHeader RequireHeader ResponseKeyHeader RetryAfterHeader RouteHeader SecurityHeader ServerHeader

SubjectHeader TimeStampHeader ToHeader UnsupportedHeader UserAgentHeader ViaHeader WarningHeader WWWAuthenticateHeader

Exceptions HeaderParseException

jain.protocol.ip.sip.header

Interface EncryptionHeader public interface EncryptionHeader extends SecurityHeader This interface represents the Encryption general-header. The EncryptionHeader specifies that the content has been encrypted. It is intended for end-to-end encryption of Requests and Responses. Requests are encrypted based on the public key belonging to the entity named in the ToHeader. Responses are encrypted based on the public key conveyed in the ResponseKeyHeader. Note that the public keys themselves may not be used for the encryption. This depends on the particular algorithms used. For any encrypted Message, at least the Message body and possibly other Message Headers are encrypted. An application receiving a Request or Response containing an EncryptionHeader decrypts the body using the private key, which returns the decrypted Message with decrypted body plus any decrypted Headers. Message Headers in the decrypted part completely replace those with the same field name in the unencrypted part. Note that the Request method and RequestURI cannot be encrypted. Encryption only provides privacy; the recipient has no guarantee that the Request or Response came from the party listed in the FromHeader, only that the sender used the recipient's public key. However, proxies will not be able to modify the Request or Response. Since proxies can base their forwarding decision on any combination of Headers, there is no guarantee that an encrypted Request "hiding" Headers will reach the same destination as an otherwise identical un-encrypted Request. Version: 0.7

Field Summary static java.lang.String name

Name of EncryptionHeader

Methods inherited from interface jain.protocol.ip.sip.header.SecurityHeader getScheme, setScheme

Methods inherited from interface jain.protocol.ip.sip.header.Header clone, equals, getName, getValue, setValue, toString

Methods inherited from interface jain.protocol.ip.sip.Parameters getParameter, getParameters, hasParameter, hasParameters, removeParameter, removeParameters, setParameter

Field Detail name public static final java.lang.String name Name of EncryptionHeader If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

Package jain.protocol.ip.sip.message This package contains the Event classes representing SIP Messages. See: Description

Interface Summary Message

This interface represents a generic SIP Message.

MessageFactory This interface provides factory methods to allow an application create Messages from a particular JAIN SIP implementation. Request

This interface represents a SIP Request i.e.

Response

This interface represents a SIP Response message.

Package jain.protocol.ip.sip.message Description This package contains the Event classes representing SIP Messages. Messages are one of the following: ● Request - sent from client to server ●

Response - sent from server to client

A Message may contain a body (entity) which contains a session description in a format such as SDP (Session Description Protocol). It also contains various Headers which add to the meaning of the Message and the Message body.

If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.message

Interface Message All Known Subinterfaces: Request, Response public interface Message extends java.lang.Cloneable, java.io.Serializable This interface represents a generic SIP Message. A Message is either a Request from a client to a server, or a Response from a server to a client. A Message may contain a body(entity) which contains a session description in a format such as SDP (Session Description Protocol). It also contains various Headers which add to the meaning of the Message and the Message body. Version: 0.7 See Also: Request, Response, Header

Method Summary void addHeader(Header header, boolean top)

Adds Header to top/bottom of Message's header list void addHeaders(java.util.List headers, boolean top)

Adds list of Headers to top/bottom of Message's header list. java.lang.Object clone()

Creates and returns copy of Message boolean equals(java.lang.Object object)

Indicates whether some other Object is "equal to" this Message (Note that obj must have the same Class as this Message - this means that it must be from the same JAIN SIP implementation) HeaderIterator getAcceptEncodingHeaders()

Gets HeaderIterator of AcceptEncodingHeaders of Message. HeaderIterator getAcceptHeaders()

Gets HeaderIterator of AcceptHeaders of Message. HeaderIterator getAcceptLanguageHeaders()

Gets HeaderIterator of AcceptLanguageHeaders of Message. byte[] getBodyAsBytes()

Gets body of Message as byte array (Returns null if no body exists) java.lang.String getBodyAsString()

Gets body of Message as String (Returns null if no body exists) CallIdHeader getCallIdHeader()

Gets CallIdHeader of Message. HeaderIterator getContactHeaders()

Gets HeaderIterator of ContactHeaders of Message.

HeaderIterator getContentEncodingHeaders()

Gets HeaderIterator of ContentEncodingHeaders of Message. ContentLengthHeader getContentLengthHeader()

Gets ContentLengthHeader of Message. ContentTypeHeader getContentTypeHeader()

Gets ContentTypeHeader of Message. CSeqHeader getCSeqHeader()

Gets CSeqHeader of Message. DateHeader getDateHeader()

Gets DateHeader of Message. EncryptionHeader getEncryptionHeader()

Gets EncryptionHeader of Message. ExpiresHeader getExpiresHeader()

Gets ExpiresHeader of Message. FromHeader getFromHeader()

Gets FromHeader of Message. Header getHeader(java.lang.String headerName, boolean first)

Gets first (or last) Header of specified name in Message (Returns null if no Headers of specified name exist) HeaderIterator getHeaders()

Gets HeaderIterator of all Headers in Message. HeaderIterator getHeaders(java.lang.String headerName)

Gets HeaderIterator of all Headers of specified name in Message. OrganizationHeader getOrganizationHeader()

Gets OrganizationHeader of Message. HeaderIterator getRecordRouteHeaders()

Gets HeaderIterator of RecordRouteHeaders of Message. RetryAfterHeader getRetryAfterHeader()

Gets RetryAfterHeader of Message. java.lang.String getStartLine()

Returns start line of Message TimeStampHeader getTimeStampHeader()

Gets TimeStampHeader of Message. ToHeader getToHeader()

Gets ToHeader of Message. UserAgentHeader getUserAgentHeader()

Gets UserAgentHeader of Message. int getVersionMajor()

Gets version major of Message. int getVersionMinor()

Gets version minor of Message.

HeaderIterator getViaHeaders()

Gets HeaderIterator of ViaHeaders of Message. boolean hasAcceptEncodingHeaders()

Gets boolean value to indicate if Message has AcceptEncodingHeaders boolean hasAcceptHeaders()

Gets boolean value to indicate if Message has AcceptHeaders boolean hasAcceptLanguageHeaders()

Gets boolean value to indicate if Message has AcceptLanguageHeaders boolean hasBody()

Gets boolean value to indicate if Message has body boolean hasContactHeaders()

Gets boolean value to indicate if Message has ContactHeaders boolean hasContentEncodingHeaders()

Gets boolean value to indicate if Message has ContentEncodingHeaders boolean hasContentLengthHeader()

Gets boolean value to indicate if Message has ContentLengthHeader boolean hasContentTypeHeader()

Gets boolean value to indicate if Message has ContentTypeHeader boolean hasDateHeader()

Gets boolean value to indicate if Message has DateHeader boolean hasEncryptionHeader()

Gets boolean value to indicate if Message has EncryptionHeader boolean hasExpiresHeader()

Gets boolean value to indicate if Message has ExpiresHeader boolean hasHeaders()

Gets boolean value to indicate if Message has any headers boolean hasHeaders(java.lang.String headerName)

Gets boolean value to indicate if Message has any headers of specified name boolean hasOrganizationHeader()

Gets boolean value to indicate if Message has OrganizationHeader boolean hasRecordRouteHeaders()

Gets boolean value to indicate if Message has RecordRouteHeaders boolean hasRetryAfterHeader()

Gets boolean value to indicate if Message has RetryAfterHeader boolean hasTimeStampHeader()

Gets boolean value to indicate if Message has TimeStampHeader boolean hasUserAgentHeader()

Gets boolean value to indicate if Message has UserAgentHeader boolean hasViaHeaders()

Gets boolean value to indicate if Message has ViaHeaders

boolean isRequest()

Returns boolean value to indicate if Message is a Request. void removeAcceptEncodingHeaders()

Removes AcceptEncodingHeaders from Message (if any exist) void removeAcceptHeaders()

Removes AcceptHeaders from Message (if any exist) void removeAcceptLanguageHeaders()

Removes AcceptLanguageHeaders from Message (if any exist) void removeBody()

Removes body from Message and all associated entity headers (if body exists) void removeContactHeaders()

Removes ContactHeaders from Message (if any exist) void removeContentEncodingHeaders()

Removes ContentEncodingHeaders from Message (if any exist) void removeContentLengthHeader()

Removes ContentLengthHeader from Message (if it exists) void removeContentTypeHeader()

Removes ContentTypeHeader from Message (if it exists) void removeDateHeader()

Removes DateHeader from Message (if it exists) void removeEncryptionHeader()

Removes EncryptionHeader from Message (if it exists) void removeExpiresHeader()

Removes ExpiresHeader from Message (if it exists) void removeHeader(java.lang.String headerName, boolean first)

Removes first (or last) Header of specified name from Message's Header list. void removeHeaders(java.lang.String headerName)

Removes all Headers of specified name from Message's Header list. void removeOrganizationHeader()

Removes OrganizationHeader from Message (if it exists) void removeRecordRouteHeaders()

Removes RecordRouteHeaders from Message (if any exist) void removeRetryAfterHeader()

Removes RetryAfterHeader from Message (if it exists) void removeTimeStampHeader()

Removes TimeStampHeader from Message (if it exists) void removeUserAgentHeader()

Removes UserAgentHeader from Message (if it exists) void removeViaHeaders()

Removes ViaHeaders from Message (if any exist)

void setAcceptEncodingHeaders(java.util.List acceptEncodingHeaders)

Sets AcceptEncodingHeaders of Message. void setAcceptHeaders(java.util.List acceptHeaders)

Sets AcceptHeaders of Message. void setAcceptLanguageHeaders(java.util.List acceptLanguageHeaders)

Sets AcceptLanguageHeaders of Message. void setBody(byte[] body, ContentTypeHeader contentTypeHeader)

Sets body of Message (with ContentTypeHeader) void setBody(java.lang.String body,

ContentTypeHeader contentTypeHeader) Sets body of Message (with ContentTypeHeader) void setCallIdHeader(CallIdHeader callIdHeader)

Sets CallIdHeader of Message. void setContactHeaders(java.util.List contactHeaders)

Sets ContactHeaders of Message. void setContentEncodingHeaders(java.util.List contentEncodingHeaders)

Sets ContentEncodingHeaders of Message. void setContentLengthHeader(ContentLengthHeader contentLengthHeader)

Sets ContentLengthHeader of Message. void setContentTypeHeader(ContentTypeHeader contentTypeHeader)

Sets ContentTypeHeader of Message. void setCSeqHeader(CSeqHeader cSeqHeader)

Sets CSeqHeader of Message. void setDateHeader(DateHeader dateHeader)

Sets DateHeader of Message. void setEncryptionHeader(EncryptionHeader encryptionHeader)

Sets EncryptionHeader of Message. void setExpiresHeader(ExpiresHeader expiresHeader)

Sets ExpiresHeader of Message. void setFromHeader(FromHeader fromHeader)

Sets FromHeader of Message. void setHeader(Header header, boolean first)

Sets the first/last Header of header's name in Message's Header list. void setHeaders(java.lang.String headerName, java.util.List headers,

boolean top) Sets all Headers of specified name in Message's header list. void setOrganizationHeader(OrganizationHeader organizationHeader)

Sets OrganizationHeader of Message. void setRecordRouteHeaders(java.util.List recordRouteHeaders)

Sets RecordRouteHeaders of Message. void setRetryAfterHeader(RetryAfterHeader retryAfterHeader)

Sets RetryAfterHeader of Message.

void setTimeStampHeader(TimeStampHeader timeStampHeader)

Sets TimeStampHeader of Message. void setToHeader(ToHeader toHeader)

Sets ToHeader of Message. void setUserAgentHeader(UserAgentHeader userAgentHeader)

Sets UserAgentHeader of Message. void setVersion(int versionMajor, int versionMinor)

Sets version of Message. void setViaHeaders(java.util.List viaHeaders)

Sets ViaHeaders of Message. java.lang.String toString()

Gets string representation of Message

Method Detail addHeaders public void addHeaders(java.util.List headers, boolean top) throws java.lang.IllegalArgumentException Adds list of Headers to top/bottom of Message's header list. Note that the Headers are added in same order as in List. Parameters: headers - List of Headers to be added top - indicates if Headers are to be added at top/bottom of Message's header list Throws: java.lang.IllegalArgumentException - if headers is null, empty, contains any null objects, or contains any objects that are not Header objects from the same JAIN SIP implementation as this Message

addHeader public void addHeader(Header header, boolean top) throws java.lang.IllegalArgumentException Adds Header to top/bottom of Message's header list Parameters: header - Header to be added top - indicates if Header is to be added at top/bottom Throws: java.lang.IllegalArgumentException - if header is null or is not from the same JAIN SIP implementation as this Message

setHeaders public void setHeaders(java.lang.String headerName, java.util.List headers, boolean top) throws java.lang.IllegalArgumentException Sets all Headers of specified name in Message's header list. Note that this method is equivalent to invoking removeHeaders(headerName) followed by addHeaders(headers, top) Parameters: headerName - name of Headers to set headers - List of Headers to be set top - indicates if Headers are to be set at top/bottom of Message's header list Throws: java.lang.IllegalArgumentException - if headerName or headers is null, if headers is empty, contains any null elements, or contains any objects that are not Header objects from the same JAIN SIP implementation as this Message, or contains any Headers that don't match the specified header name

setHeader public void setHeader(Header header, boolean first) throws java.lang.IllegalArgumentException Sets the first/last Header of header's name in Message's Header list. Note that this method is equivalent to invoking removeHeader(headerName, first) followed by addHeader(header, first) Parameters: header - Header to set first - indicates if first/last Header is to be set Throws: java.lang.IllegalArgumentException - if header is null or is not from the same JAIN SIP implementation as this Message

removeHeader public void removeHeader(java.lang.String headerName, boolean first) throws java.lang.IllegalArgumentException Removes first (or last) Header of specified name from Message's Header list. Note if no Headers of specified name exist the method has no effect Parameters: headerName - name of Header to be removed first - indicates whether first or last Header of specified name is to be removed Throws: java.lang.IllegalArgumentException - if headerName is null

removeHeaders public void removeHeaders(java.lang.String headerName) throws java.lang.IllegalArgumentException Removes all Headers of specified name from Message's Header list. Note if no Headers of specified name exist the method has no effect Parameters: headername - name of Headers to be removed Throws: java.lang.IllegalArgumentException - if headerType is null

getHeaders public HeaderIterator getHeaders() Gets HeaderIterator of all Headers in Message. Note that order of Headers in HeaderIterator is same as order in Message (Returns null if no Headers exist) Returns: HeaderIterator of all Headers in Message

getHeaders public HeaderIterator getHeaders(java.lang.String headerName) throws java.lang.IllegalArgumentException Gets HeaderIterator of all Headers of specified name in Message. Note that order of Headers in HeaderIterator is same as order they appear in Message (Returns null if no Headers of specified name exist) Parameters: headerName - name of Headers to return Returns: HeaderIterator of all Headers of specified name in Message Throws: java.lang.IllegalArgumentException - if headerName is null

getHeader public Header getHeader(java.lang.String headerName, boolean first) throws java.lang.IllegalArgumentException, HeaderParseException Gets first (or last) Header of specified name in Message (Returns null if no Headers of specified name exist) Parameters: headerName - name of Header to return first - indicates whether the first or last Header of specified name is required

Returns: first (or last) Header of specified name in Message's Header list Throws: java.lang.IllegalArgumentException - if headername is null HeaderParseException - if implementation could not parse header value

hasHeaders public boolean hasHeaders() Gets boolean value to indicate if Message has any headers Returns: boolean value to indicate if Message has any headers

hasHeaders public boolean hasHeaders(java.lang.String headerName) throws java.lang.IllegalArgumentException Gets boolean value to indicate if Message has any headers of specified name Parameters: headerName - header name Returns: boolean value to indicate if Message has any headers of specified name Throws: java.lang.IllegalArgumentException - if headerName is null

getCallIdHeader public CallIdHeader getCallIdHeader() Gets CallIdHeader of Message. (Returns null if no CallIdHeader exists) Returns: CallIdHeader of Message

setCallIdHeader public void setCallIdHeader(CallIdHeader callIdHeader) throws java.lang.IllegalArgumentException Sets CallIdHeader of Message. Parameters: callIdHeader - CallIdHeader to set Throws: java.lang.IllegalArgumentException - if callIdHeader is null or not from same JAIN SIP implementation

getCSeqHeader public CSeqHeader getCSeqHeader() Gets CSeqHeader of Message. (Returns null if no CSeqHeader exists) Returns: CSeqHeader of Message

setCSeqHeader public void setCSeqHeader(CSeqHeader cSeqHeader) throws java.lang.IllegalArgumentException Sets CSeqHeader of Message. Parameters: cSeqHeader - CSeqHeader to set Throws: java.lang.IllegalArgumentException - if cSeqHeader is null or not from same JAIN SIP implementation

getToHeader public ToHeader getToHeader() Gets ToHeader of Message. (Returns null if no CSeqHeader exists) Returns: ToHeader of Message Throws: HeaderNotSetException - if no ToHeader exists

setToHeader public void setToHeader(ToHeader toHeader) throws java.lang.IllegalArgumentException Sets ToHeader of Message. Parameters: toHeader - ToHeader to set Throws: java.lang.IllegalArgumentException - if toHeader is null or not from same JAIN SIP implementation

getFromHeader public FromHeader getFromHeader() Gets FromHeader of Message. (Returns null if no CSeqHeader exists) Returns: FromHeader of Message Throws: HeaderNotSetException - if no FromHeader exists

setFromHeader public void setFromHeader(FromHeader fromHeader) throws java.lang.IllegalArgumentException Sets FromHeader of Message. Parameters: fromHeader - FromHeader to set Throws: java.lang.IllegalArgumentException - if fromHeader is null or not from same JAIN SIP implementation

getViaHeaders public HeaderIterator getViaHeaders() Gets HeaderIterator of ViaHeaders of Message. (Returns null if no ViaHeaders exist) Returns: HeaderIterator of ViaHeaders of Message

setViaHeaders public void setViaHeaders(java.util.List viaHeaders) throws java.lang.IllegalArgumentException Sets ViaHeaders of Message. Parameters: viaHeaders - List of ViaHeaders to set Throws: java.lang.IllegalArgumentException - if viaHeaders is null, empty, contains any elements that are null or not ViaHeaders from the same JAIN SIP implementation

hasViaHeaders public boolean hasViaHeaders()

Gets boolean value to indicate if Message has ViaHeaders Returns: boolean value to indicate if Message has ViaHeaders

removeViaHeaders public void removeViaHeaders() Removes ViaHeaders from Message (if any exist)

getContentTypeHeader public ContentTypeHeader getContentTypeHeader() throws HeaderParseException Gets ContentTypeHeader of Message. (Returns null if no ContentTypeHeader exists) Returns: ContentTypeHeader of Message Throws: HeaderParseException - if implementation could not parse header value

setContentTypeHeader public void setContentTypeHeader(ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipException Sets ContentTypeHeader of Message. Parameters: contentTypeHeader - ContentTypeHeader to set Throws: java.lang.IllegalArgumentException - if contentTypeHeader is null or not from same JAIN SIP implementation SipException - if Message does not contain body

hasContentTypeHeader public boolean hasContentTypeHeader() Gets boolean value to indicate if Message has ContentTypeHeader Returns: boolean value to indicate if Message has ContentTypeHeader

removeContentTypeHeader public void removeContentTypeHeader() Removes ContentTypeHeader from Message (if it exists)

getDateHeader public DateHeader getDateHeader() throws HeaderParseException Gets DateHeader of Message. (Returns null if no DateHeader exists) Returns: DateHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasDateHeader public boolean hasDateHeader() Gets boolean value to indicate if Message has DateHeader Returns: boolean value to indicate if Message has DateHeader

setDateHeader public void setDateHeader(DateHeader dateHeader) throws java.lang.IllegalArgumentException Sets DateHeader of Message. Parameters: dateHeader - DateHeader to set Throws: java.lang.IllegalArgumentException - if dateHeader is null or not from same JAIN SIP implementation

removeDateHeader public void removeDateHeader() Removes DateHeader from Message (if it exists)

getEncryptionHeader public EncryptionHeader getEncryptionHeader() throws HeaderParseException Gets EncryptionHeader of Message. (Returns null if no EncryptionHeader exists) Returns: EncryptionHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasEncryptionHeader public boolean hasEncryptionHeader() Gets boolean value to indicate if Message has EncryptionHeader Returns: boolean value to indicate if Message has EncryptionHeader

setEncryptionHeader public void setEncryptionHeader(EncryptionHeader encryptionHeader) throws java.lang.IllegalArgumentException Sets EncryptionHeader of Message. Parameters: encryptionHeader - EncryptionHeader to set Throws: java.lang.IllegalArgumentException - if encryptionHeader is null or not from same JAIN SIP implementation

removeEncryptionHeader public void removeEncryptionHeader() Removes EncryptionHeader from Message (if it exists)

getUserAgentHeader public UserAgentHeader getUserAgentHeader() throws HeaderParseException Gets UserAgentHeader of Message. (Returns null if no UserAgentHeader exists) Returns: UserAgentHeader of Message Throws:

HeaderParseException - if implementation could not parse header value

hasUserAgentHeader public boolean hasUserAgentHeader() Gets boolean value to indicate if Message has UserAgentHeader Returns: boolean value to indicate if Message has UserAgentHeader

setUserAgentHeader public void setUserAgentHeader(UserAgentHeader userAgentHeader) throws java.lang.IllegalArgumentException Sets UserAgentHeader of Message. Parameters: userAgentHeader - UserAgentHeader to set Throws: java.lang.IllegalArgumentException - if userAgentHeader is null or not from same JAIN SIP implementation

removeUserAgentHeader public void removeUserAgentHeader() Removes UserAgentHeader from Message (if it exists)

getTimeStampHeader public TimeStampHeader getTimeStampHeader() throws HeaderParseException Gets TimeStampHeader of Message. (Returns null if no TimeStampHeader exists) Returns: TimeStampHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasTimeStampHeader public boolean hasTimeStampHeader() Gets boolean value to indicate if Message has TimeStampHeader Returns: boolean value to indicate if Message has TimeStampHeader

removeTimeStampHeader public void removeTimeStampHeader() Removes TimeStampHeader from Message (if it exists)

setTimeStampHeader public void setTimeStampHeader(TimeStampHeader timeStampHeader) throws java.lang.IllegalArgumentException Sets TimeStampHeader of Message. Parameters: timeStampHeader - TimeStampHeader to set Throws: java.lang.IllegalArgumentException - if timeStampHeader is null or not from same JAIN SIP implementation

getContentEncodingHeaders public HeaderIterator getContentEncodingHeaders() Gets HeaderIterator of ContentEncodingHeaders of Message. (Returns null if no ContentEncodingHeaders exist) Returns: HeaderIterator of ContentEncodingHeaders of Message

hasContentEncodingHeaders public boolean hasContentEncodingHeaders() Gets boolean value to indicate if Message has ContentEncodingHeaders Returns: boolean value to indicate if Message has ContentEncodingHeaders

removeContentEncodingHeaders public void removeContentEncodingHeaders() Removes ContentEncodingHeaders from Message (if any exist)

setContentEncodingHeaders public void setContentEncodingHeaders(java.util.List contentEncodingHeaders) throws java.lang.IllegalArgumentException, SipException

Sets ContentEncodingHeaders of Message. Parameters: contentEncodingHeaders - List of ContentEncodingHeaders to set Throws: java.lang.IllegalArgumentException - if contentEncodingHeaders is null, empty, contains any elements that are null or not ContentEncodingHeaders from the same JAIN SIP implementation

getContentLengthHeader public ContentLengthHeader getContentLengthHeader() throws HeaderParseException Gets ContentLengthHeader of Message. (Returns null if no ContentLengthHeader exists) Returns: ContentLengthHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasContentLengthHeader public boolean hasContentLengthHeader() Gets boolean value to indicate if Message has ContentLengthHeader Returns: boolean value to indicate if Message has ContentLengthHeader

removeContentLengthHeader public void removeContentLengthHeader() Removes ContentLengthHeader from Message (if it exists)

setContentLengthHeader public void setContentLengthHeader(ContentLengthHeader contentLengthHeader) throws java.lang.IllegalArgumentException Sets ContentLengthHeader of Message. Parameters: contentLengthHeader - ContentLengthHeader to set Throws: java.lang.IllegalArgumentException - if contentLengthHeader is null or not from same JAIN SIP implementation

getAcceptHeaders public HeaderIterator getAcceptHeaders() Gets HeaderIterator of AcceptHeaders of Message. (Returns null if no AcceptHeaders exist) Returns: HeaderIterator of AcceptHeaders of Message

hasAcceptHeaders public boolean hasAcceptHeaders() Gets boolean value to indicate if Message has AcceptHeaders Returns: boolean value to indicate if Message has AcceptHeaders

removeAcceptHeaders public void removeAcceptHeaders() Removes AcceptHeaders from Message (if any exist)

setAcceptHeaders public void setAcceptHeaders(java.util.List acceptHeaders) throws java.lang.IllegalArgumentException Sets AcceptHeaders of Message. Parameters: acceptHeaders - List of AcceptHeaders to set Throws: java.lang.IllegalArgumentException - if acceptHeaders is null, empty, contains any elements that are null or not AcceptHeaders from the same JAIN SIP implementation

getAcceptEncodingHeaders public HeaderIterator getAcceptEncodingHeaders() Gets HeaderIterator of AcceptEncodingHeaders of Message. (Returns null if no AcceptEncodingHeaders exist) Returns: HeaderIterator of AcceptEncodingHeaders of Message

hasAcceptEncodingHeaders public boolean hasAcceptEncodingHeaders() Gets boolean value to indicate if Message has AcceptEncodingHeaders Returns: boolean value to indicate if Message has AcceptEncodingHeaders

removeAcceptEncodingHeaders public void removeAcceptEncodingHeaders() Removes AcceptEncodingHeaders from Message (if any exist)

setAcceptEncodingHeaders public void setAcceptEncodingHeaders(java.util.List acceptEncodingHeaders) throws java.lang.IllegalArgumentException Sets AcceptEncodingHeaders of Message. Parameters: acceptEncodingHeaders - List of AcceptEncodingHeaders to set Throws: java.lang.IllegalArgumentException - if acceptEncodingHeaders is null, empty, contains any elements that are null or not AcceptEncodingHeaders from the same JAIN SIP implementation

getAcceptLanguageHeaders public HeaderIterator getAcceptLanguageHeaders() Gets HeaderIterator of AcceptLanguageHeaders of Message. (Returns null if no AcceptLanguageHeaders exist) Returns: HeaderIterator of AcceptLanguageHeaders of Message

hasAcceptLanguageHeaders public boolean hasAcceptLanguageHeaders() Gets boolean value to indicate if Message has AcceptLanguageHeaders Returns: boolean value to indicate if Message has AcceptLanguageHeaders

removeAcceptLanguageHeaders public void removeAcceptLanguageHeaders() Removes AcceptLanguageHeaders from Message (if any exist)

setAcceptLanguageHeaders public void setAcceptLanguageHeaders(java.util.List acceptLanguageHeaders) throws java.lang.IllegalArgumentException Sets AcceptLanguageHeaders of Message. Parameters: acceptLanguageHeaders - List of AcceptLanguageHeaders to set Throws: java.lang.IllegalArgumentException - if acceptLanguageHeaders is null, empty, contains any elements that are null or not AcceptLanguageHeaders from the same JAIN SIP implementation

getExpiresHeader public ExpiresHeader getExpiresHeader() throws HeaderParseException Gets ExpiresHeader of Message. (Returns null if no ExpiresHeader exists) Returns: ExpiresHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasExpiresHeader public boolean hasExpiresHeader() Gets boolean value to indicate if Message has ExpiresHeader Returns: boolean value to indicate if Message has ExpiresHeader

removeExpiresHeader public void removeExpiresHeader() Removes ExpiresHeader from Message (if it exists)

setExpiresHeader public void setExpiresHeader(ExpiresHeader expiresHeader) throws java.lang.IllegalArgumentException Sets ExpiresHeader of Message. Parameters: expiresHeader - ExpiresHeader to set Throws: java.lang.IllegalArgumentException - if expiresHeader is null or not from same JAIN SIP implementation

getContactHeaders public HeaderIterator getContactHeaders() Gets HeaderIterator of ContactHeaders of Message. (Returns null if no ContactHeaders exist) Returns: HeaderIterator of ContactHeaders of Message

hasContactHeaders public boolean hasContactHeaders() Gets boolean value to indicate if Message has ContactHeaders Returns: boolean value to indicate if Message has ContactHeaders

removeContactHeaders public void removeContactHeaders() Removes ContactHeaders from Message (if any exist)

setContactHeaders public void setContactHeaders(java.util.List contactHeaders) throws java.lang.IllegalArgumentException Sets ContactHeaders of Message. Parameters: contactHeaders - List of ContactHeaders to set Throws: java.lang.IllegalArgumentException - if contactHeaders is null, empty, contains any elements that are null or not ContactHeaders from the same JAIN SIP implementation

getOrganizationHeader public OrganizationHeader getOrganizationHeader() throws HeaderParseException Gets OrganizationHeader of Message. (Returns null if no OrganizationHeader exists) Returns: OrganizationHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasOrganizationHeader public boolean hasOrganizationHeader() Gets boolean value to indicate if Message has OrganizationHeader Returns: boolean value to indicate if Message has OrganizationHeader

removeOrganizationHeader public void removeOrganizationHeader() Removes OrganizationHeader from Message (if it exists)

setOrganizationHeader public void setOrganizationHeader(OrganizationHeader organizationHeader) throws java.lang.IllegalArgumentException Sets OrganizationHeader of Message. Parameters: organizationHeader - OrganizationHeader to set Throws: java.lang.IllegalArgumentException - if organizationHeader is null or not from same JAIN SIP implementation

getRecordRouteHeaders public HeaderIterator getRecordRouteHeaders() Gets HeaderIterator of RecordRouteHeaders of Message. (Returns null if no RecordRouteHeaders exist) Returns: HeaderIterator of RecordRouteHeaders of Message

hasRecordRouteHeaders public boolean hasRecordRouteHeaders() Gets boolean value to indicate if Message has RecordRouteHeaders Returns: boolean value to indicate if Message has RecordRouteHeaders

removeRecordRouteHeaders public void removeRecordRouteHeaders() Removes RecordRouteHeaders from Message (if any exist)

setRecordRouteHeaders public void setRecordRouteHeaders(java.util.List recordRouteHeaders) throws java.lang.IllegalArgumentException Sets RecordRouteHeaders of Message. Parameters: recordRouteHeaders - List of RecordRouteHeaders to set Throws: java.lang.IllegalArgumentException - if recordRouteHeaders is null, empty, contains any elements that are null or not RecordRouteHeaders from the same JAIN SIP implementation

getRetryAfterHeader public RetryAfterHeader getRetryAfterHeader() throws HeaderParseException Gets RetryAfterHeader of Message. (Returns null if no RetryAfterHeader exists) Returns: RetryAfterHeader of Message Throws: HeaderParseException - if implementation could not parse header value

hasRetryAfterHeader public boolean hasRetryAfterHeader() Gets boolean value to indicate if Message has RetryAfterHeader Returns: boolean value to indicate if Message has RetryAfterHeader

removeRetryAfterHeader public void removeRetryAfterHeader() Removes RetryAfterHeader from Message (if it exists)

setRetryAfterHeader public void setRetryAfterHeader(RetryAfterHeader retryAfterHeader) throws java.lang.IllegalArgumentException Sets RetryAfterHeader of Message. Parameters: retryAfterHeader - RetryAfterHeader to set Throws: java.lang.IllegalArgumentException - if retryAfterHeader is null or not from same JAIN SIP implementation

getBodyAsString public java.lang.String getBodyAsString() Gets body of Message as String (Returns null if no body exists) Returns: body of Message as String

getBodyAsBytes public byte[] getBodyAsBytes() Gets body of Message as byte array (Returns null if no body exists) Returns: body of Message as byte array

hasBody public boolean hasBody() Gets boolean value to indicate if Message has body Returns: boolean value to indicate if Message has body

setBody public void setBody(java.lang.String body, ContentTypeHeader contentTypeHeader)

throws java.lang.IllegalArgumentException, SipParseException Sets body of Message (with ContentTypeHeader) Parameters: body - body to set contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body or contentTypeHeader is null, or contentTypeHeader is not from same JAIN SIP implementation SipParseException - if body is not accepted by implementation

setBody public void setBody(byte[] body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Sets body of Message (with ContentTypeHeader) Parameters: body - body to set contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body or contentTypeHeader is null, or contentTypeHeader is not from same JAIN SIP implementation SipParseException - if body is not accepted by implementation

removeBody public void removeBody() Removes body from Message and all associated entity headers (if body exists)

getVersionMajor public int getVersionMajor() throws SipParseException Gets version major of Message. Returns: version major of Message Throws: SipParseException - if implementation could not parse version major

getVersionMinor public int getVersionMinor() throws SipParseException Gets version minor of Message. Returns: version minor of Message Throws: SipParseException - if implementation could not parse version minor

setVersion public void setVersion(int versionMajor, int versionMinor) throws SipParseException Sets version of Message. Note that the version defaults to 2.0. (i.e. version major of 2 and version minor of 0) Parameters: versionMajor - version major versionMinor - version minor Throws: SipParseException - if versionMajor or versionMinor are not accepted by implementation

isRequest public boolean isRequest() Returns boolean value to indicate if Message is a Request. Returns: boolean value to indicate if Message is a Request

getStartLine public java.lang.String getStartLine() Returns start line of Message Returns: start line of Message

equals public boolean equals(java.lang.Object object) Indicates whether some other Object is "equal to" this Message (Note that obj must have the same Class as this Message - this means that it must be from the same JAIN SIP implementation)

Overrides: equals in class java.lang.Object Parameters: obj - the Object with which to compare this Message

clone public java.lang.Object clone() Creates and returns copy of Message

toString public java.lang.String toString() Gets string representation of Message Overrides: toString in class java.lang.Object Returns: string representation of Message If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.message

Interface MessageFactory public interface MessageFactory This interface provides factory methods to allow an application create Messages from a particular JAIN SIP implementation.

Method Summary Request createRequest(URI requestURI, java.lang.String method,

CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders) Creates Request without body Request createRequest(URI requestURI, java.lang.String method,

CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, byte[] body, ContentTypeHeader contentTypeHeader) Creates Request with body Request createRequest(URI requestURI, java.lang.String method,

CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, java.lang.String body, ContentTypeHeader contentTypeHeader) Creates Request with body Response createResponse(int statusCode, CallIdHeader callIdHeader,

CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders) Creates Response without body Response createResponse(int statusCode, CallIdHeader callIdHeader,

CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, byte[] body, ContentTypeHeader contentTypeHeader) Creates Response with body

Response createResponse(int statusCode, CallIdHeader callIdHeader,

CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, java.lang.String body, ContentTypeHeader contentTypeHeader) Creates Response with body Response createResponse(int statusCode, Request request)

Creates Response without body based on specified Request Response createResponse(int statusCode, Request request, byte[] body,

ContentTypeHeader contentTypeHeader) Creates Response with body based on specified Request Response createResponse(int statusCode, Request request,

java.lang.String body, ContentTypeHeader contentTypeHeader) Creates Response with body based on specified Request

Method Detail createRequest public Request createRequest(URI requestURI, java.lang.String method, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders) throws java.lang.IllegalArgumentException, SipParseException Creates Request without body Parameters: requestURI - Request URI method - Request method callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader toHeader - ToHeader viaHeaders - ViaHeaders

Throws: java.lang.IllegalArgumentException - if method is null, or if requestURI, callIdHeader, cSeqHeader, fromHeader or toHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation SipParseException - if method is not accepted by implementation

createRequest public Request createRequest(URI requestURI, java.lang.String method, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, java.lang.String body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Request with body Parameters: requestURI - Request URI method - Request method callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader toHeader - ToHeader viaHeaders - ViaHeaders body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if method or body are null, if requestURI, callIdHeader, cSeqHeader, fromHeader, toHeader or contentTypeHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation SipParseException - if method or body are not accepted by implementation

createRequest public Request createRequest(URI requestURI, java.lang.String method, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, byte[] body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Request with body Parameters: requestURI - Request URI method - Request method callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader toHeader - ToHeader viaHeaders - ViaHeaders body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if method or body are null, if requestURI, callIdHeader, cSeqHeader, fromHeader, toHeader or contentTypeHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation SipParseException - if method or body are not accepted by implementation

createResponse public Response createResponse(int statusCode, CallIdHeader callIdHeader, CSeqHeader cSeqHeader,

FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders) throws java.lang.IllegalArgumentException, SipParseException Creates Response without body Parameters: statusCode - status code callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader toHeader - ToHeader viaHeaders - ViaHeaders Throws: java.lang.IllegalArgumentException - if callIdHeader, cSeqHeader, fromHeader or toHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation SipParseException - if statusCode is not accepted by implementation

createResponse public Response createResponse(int statusCode, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, byte[] body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Response with body Parameters: statusCode - status code callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader

toHeader - ToHeader viaHeaders - ViaHeaders body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body is null, or if callIdHeader, cSeqHeader, fromHeader, toHeader or contentTypeHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation SipParseException - if statusCode or body are not accepted by implementation

createResponse public Response createResponse(int statusCode, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, java.util.List viaHeaders, java.lang.String body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Response with body Parameters: statusCode - status code callIdHeader - CallIdHeader cSeqHeader - CSeqHeader fromHeader - FromHeader toHeader - ToHeader viaHeaders - ViaHeaders body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body is null, or if callIdHeader, cSeqHeader, fromHeader, toHeader or contentTypeHeader are null or not from same JAIN SIP implementation, or if viaHeaders is null, empty, contains any null elements, or contains any objects that are not ViaHeaders from the same JAIN SIP implementation

SipParseException - if statusCode or body are not accepted by implementation

createResponse public Response createResponse(int statusCode, Request request) throws java.lang.IllegalArgumentException, SipParseException Creates Response without body based on specified Request Parameters: statusCode - status code request - Request to base Response on Throws: java.lang.IllegalArgumentException - if request is null or not from same JAIN SIP implementation SipParseException - if statusCode is not accepted by implementation

createResponse public Response createResponse(int statusCode, Request request, byte[] body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Response with body based on specified Request Parameters: statusCode - status code request - Request to base Response on body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body is null, or if request or contentTypeHeader are null or not from same JAIN SIP implementation SipParseException - if statusCode or body are not accepted by implementation

createResponse public Response createResponse(int statusCode, Request request, java.lang.String body, ContentTypeHeader contentTypeHeader) throws java.lang.IllegalArgumentException, SipParseException Creates Response with body based on specified Request Parameters: statusCode - status code request - Request to base Response on body - body of Request contentTypeHeader - ContentTypeHeader Throws: java.lang.IllegalArgumentException - if body is null, or if request or contentTypeHeader are null or not from same JAIN SIP implementation SipParseException - if statusCode or body are not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.message

Interface Request public interface Request extends Message This interface represents a SIP Request i.e. a request from a client to a server. There are six defined methods for a Request in the JAIN SIP API: ● ACK - confirms that client has received a final Response to an INVITE Request ● BYE - indicates to the server that client wishes to release the call leg ● CANCEL - cancels a pending Request ● INVITE - indicates that user or service is being invited to participate in a session ● OPTIONS - queries server as to its capabilities ● REGISTER - register address with a SIP server Ceratin Requests may contain a body(entity) which contains a session description in a format such as SDP (Session Description Protocol). Requests also contain various Headers which describe the routing of the message and the message body. Version: 0.7

Field Summary static java.lang.String ACK

ACK method constant static java.lang.String BYE

BYE method constant static java.lang.String CANCEL

CANCEL method constant static java.lang.String INVITE

INVITE method constant static java.lang.String OPTIONS

OPTIONS method constant static java.lang.String REGISTER

REGISTER method constant

Method Summary void addViaHeader(ViaHeader viaHeader)

Adds ViaHeader to top of Request's ViaHeaders. AuthorizationHeader getAuthorizationHeader()

Gets AuthorizationHeader of Request. HideHeader getHideHeader()

Gets HideHeader of Request. MaxForwardsHeader getMaxForwardsHeader()

Gets MaxForwardsHeader of Request. java.lang.String getMethod()

Gets method of Request. PriorityHeader getPriorityHeader()

Gets PriorityHeader of Request. ProxyAuthorizationHeader getProxyAuthorizationHeader()

Gets ProxyAuthorizationHeader of Request. HeaderIterator getProxyRequireHeaders()

Gets HeaderIterator of ProxyRequireHeaders of Request.

URI getRequestURI()

Gets Request URI of Request. HeaderIterator getRequireHeaders()

Gets HeaderIterator of RequireHeaders of Request. ResponseKeyHeader getResponseKeyHeader()

Gets ResponseKeyHeader of Request. HeaderIterator getRouteHeaders()

Gets HeaderIterator of RouteHeaders of Request. SubjectHeader getSubjectHeader()

Gets SubjectHeader of InviteMessage. boolean hasAuthorizationHeader()

Gets boolean value to indicate if Request has AuthorizationHeader boolean hasHideHeader()

Gets boolean value to indicate if Request has HideHeader boolean hasMaxForwardsHeader()

Gets boolean value to indicate if Request has MaxForwardsHeader boolean hasPriorityHeader()

Gets boolean value to indicate if Request has PriorityHeader boolean hasProxyAuthorizationHeader()

Gets boolean value to indicate if Request has ProxyAuthorizationHeader boolean hasProxyRequireHeaders()

Gets boolean value to indicate if Request has ProxyRequireHeaders boolean hasRequireHeaders()

Gets boolean value to indicate if Request has RequireHeaders boolean hasResponseKeyHeader()

Gets boolean value to indicate if Request has ResponseKeyHeader boolean hasRouteHeaders()

Gets boolean value to indicate if Request has RouteHeaders boolean hasSubjectHeader()

Gets boolean value to indicate if Request has SubjectHeader void removeAuthorizationHeader()

Removes AuthorizationHeader from Request (if it exists) void removeHideHeader()

Removes HideHeader from Request (if it exists) void removeMaxForwardsHeader()

Removes MaxForwardsHeader from Request (if it exists) void removePriorityHeader()

Removes PriorityHeader from Request (if it exists) void removeProxyAuthorizationHeader()

Removes ProxyAuthorizationHeader from Request (if it exists) void removeProxyRequireHeaders()

Removes ProxyRequireHeaders from Request (if any exist) void removeRequireHeaders()

Removes RequireHeaders from Request (if any exist) void removeResponseKeyHeader()

Removes ResponseKeyHeader from Request (if it exists) void removeRouteHeaders()

Removes RouteHeaders from Request (if any exist) void removeSubjectHeader()

Removes SubjectHeader from Request (if it exists)

void setAuthorizationHeader(AuthorizationHeader authorizationHeader)

Sets AuthorizationHeader of Request. void setHideHeader(HideHeader hideHeader)

Sets HideHeader of Request. void setMaxForwardsHeader(MaxForwardsHeader maxForwardsHeader)

Sets MaxForwardsHeader of Request. void setPriorityHeader(PriorityHeader priorityHeader)

Sets PriorityHeader of Request. void setProxyAuthorizationHeader(ProxyAuthorizationHeader proxyAuthorizationHeader)

Sets ProxyAuthorizationHeader of Request. void setProxyRequireHeaders(java.util.List proxyRequireHeaders)

Sets ProxyRequireHeaders of Request. void setRequestURI(URI requestURI)

Sets RequestURI of Request. void setRequireHeaders(java.util.List requireHeaders)

Sets RequireHeaders of Request. void setResponseKeyHeader(ResponseKeyHeader responseKeyHeader)

Sets ResponseKeyHeader of Request. void setRouteHeaders(java.util.List routeHeaders)

Sets RouteHeaders of Request. void setSubjectHeader(SubjectHeader subjectHeader)

Sets SubjectHeader of InviteMessage.

Methods inherited from interface jain.protocol.ip.sip.message.Message addHeader, addHeaders, clone, equals, getAcceptEncodingHeaders, getAcceptHeaders, getAcceptLanguageHeaders, getBodyAsBytes, getBodyAsString, getCallIdHeader, getContactHeaders, getContentEncodingHeaders, getContentLengthHeader, getContentTypeHeader, getCSeqHeader, getDateHeader, getEncryptionHeader, getExpiresHeader, getFromHeader, getHeader, getHeaders, getHeaders, getOrganizationHeader, getRecordRouteHeaders, getRetryAfterHeader, getStartLine, getTimeStampHeader, getToHeader, getUserAgentHeader, getVersionMajor, getVersionMinor, getViaHeaders, hasAcceptEncodingHeaders, hasAcceptHeaders, hasAcceptLanguageHeaders, hasBody, hasContactHeaders, hasContentEncodingHeaders, hasContentLengthHeader, hasContentTypeHeader, hasDateHeader, hasEncryptionHeader, hasExpiresHeader, hasHeaders, hasHeaders, hasOrganizationHeader, hasRecordRouteHeaders, hasRetryAfterHeader, hasTimeStampHeader, hasUserAgentHeader, hasViaHeaders, isRequest, removeAcceptEncodingHeaders, removeAcceptHeaders, removeAcceptLanguageHeaders, removeBody, removeContactHeaders, removeContentEncodingHeaders, removeContentLengthHeader, removeContentTypeHeader, removeDateHeader, removeEncryptionHeader, removeExpiresHeader, removeHeader, removeHeaders, removeOrganizationHeader, removeRecordRouteHeaders, removeRetryAfterHeader, removeTimeStampHeader, removeUserAgentHeader, removeViaHeaders, setAcceptEncodingHeaders, setAcceptHeaders, setAcceptLanguageHeaders, setBody, setBody, setCallIdHeader, setContactHeaders, setContentEncodingHeaders, setContentLengthHeader, setContentTypeHeader, setCSeqHeader, setDateHeader, setEncryptionHeader, setExpiresHeader, setFromHeader, setHeader, setHeaders, setOrganizationHeader, setRecordRouteHeaders, setRetryAfterHeader, setTimeStampHeader, setToHeader, setUserAgentHeader, setVersion, setViaHeaders, toString

Field Detail INVITE public static final java.lang.String INVITE INVITE method constant

ACK public static final java.lang.String ACK ACK method constant

BYE public static final java.lang.String BYE BYE method constant

CANCEL public static final java.lang.String CANCEL CANCEL method constant

OPTIONS public static final java.lang.String OPTIONS OPTIONS method constant

REGISTER public static final java.lang.String REGISTER REGISTER method constant

Method Detail addViaHeader public void addViaHeader(ViaHeader viaHeader) throws java.lang.IllegalArgumentException Adds ViaHeader to top of Request's ViaHeaders. Parameters: viaHeader - ViaHeader to add Throws: java.lang.IllegalArgumentException - if viaHeader is null or not from same JAIN SIP implementation

getMethod public java.lang.String getMethod() throws SipParseException Gets method of Request. Returns: method of Request Throws: SipParseException - if implementation cannot parse method

getRequestURI public URI getRequestURI() throws SipParseException Gets Request URI of Request. Returns: Request URI of Request Throws: SipParseException - if implementation cannot parse Request URI

setRequestURI public void setRequestURI(URI requestURI) throws java.lang.IllegalArgumentException Sets RequestURI of Request. Parameters: requestURI - Request URI to set Throws: java.lang.IllegalArgumentException - if requestURI is null or not from same JAIN SIP implementation

getAuthorizationHeader public AuthorizationHeader getAuthorizationHeader() throws HeaderParseException Gets AuthorizationHeader of Request. (Returns null if no AuthorizationHeader exists) Returns: AuthorizationHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasAuthorizationHeader public boolean hasAuthorizationHeader() Gets boolean value to indicate if Request has AuthorizationHeader Returns: boolean value to indicate if Request has AuthorizationHeader

setAuthorizationHeader public void setAuthorizationHeader(AuthorizationHeader authorizationHeader) throws java.lang.IllegalArgumentException Sets AuthorizationHeader of Request. Parameters: authorizationHeader - AuthorizationHeader to set Throws: java.lang.IllegalArgumentException - if authorizationHeader is null or not from same JAIN SIP implementation

removeAuthorizationHeader public void removeAuthorizationHeader() Removes AuthorizationHeader from Request (if it exists)

getHideHeader public HideHeader getHideHeader() throws HeaderParseException Gets HideHeader of Request. (Returns null if no AuthorizationHeader exists) Returns: HideHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasHideHeader public boolean hasHideHeader() Gets boolean value to indicate if Request has HideHeader Returns: boolean value to indicate if Request has HideHeader

setHideHeader public void setHideHeader(HideHeader hideHeader) throws java.lang.IllegalArgumentException Sets HideHeader of Request. Parameters: hideHeader - HideHeader to set Throws: java.lang.IllegalArgumentException - if hideHeader is null or not from same JAIN SIP implementation

removeHideHeader public void removeHideHeader() Removes HideHeader from Request (if it exists)

getMaxForwardsHeader public MaxForwardsHeader getMaxForwardsHeader() throws HeaderParseException Gets MaxForwardsHeader of Request. (Returns null if no MaxForwardsHeader exists) Returns: MaxForwardsHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasMaxForwardsHeader public boolean hasMaxForwardsHeader() Gets boolean value to indicate if Request has MaxForwardsHeader Returns: boolean value to indicate if Request has MaxForwardsHeader

setMaxForwardsHeader public void setMaxForwardsHeader(MaxForwardsHeader maxForwardsHeader) throws java.lang.IllegalArgumentException Sets MaxForwardsHeader of Request. Parameters: maxForwardsHeader - MaxForwardsHeader to set Throws: java.lang.IllegalArgumentException - if maxForwardsHeader is null or not from same JAIN SIP implementation

removeMaxForwardsHeader public void removeMaxForwardsHeader() Removes MaxForwardsHeader from Request (if it exists)

getProxyAuthorizationHeader public ProxyAuthorizationHeader getProxyAuthorizationHeader() throws HeaderParseException Gets ProxyAuthorizationHeader of Request. (Returns null if no ProxyAuthorizationHeader exists) Returns: ProxyAuthorizationHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasProxyAuthorizationHeader public boolean hasProxyAuthorizationHeader() Gets boolean value to indicate if Request has ProxyAuthorizationHeader Returns: boolean value to indicate if Request has ProxyAuthorizationHeader

setProxyAuthorizationHeader public void setProxyAuthorizationHeader(ProxyAuthorizationHeader proxyAuthorizationHeader) throws java.lang.IllegalArgumentException Sets ProxyAuthorizationHeader of Request. Parameters: proxyAuthorizationHeader - ProxyAuthorizationHeader to set Throws: java.lang.IllegalArgumentException - if proxyAuthorizationHeader is null or not from same JAIN SIP implementation

removeProxyAuthorizationHeader public void removeProxyAuthorizationHeader() Removes ProxyAuthorizationHeader from Request (if it exists)

getProxyRequireHeaders public HeaderIterator getProxyRequireHeaders() Gets HeaderIterator of ProxyRequireHeaders of Request. (Returns null if no ProxyRequireHeaders exist) Returns: HeaderIterator of ProxyRequireHeaders of Request

hasProxyRequireHeaders public boolean hasProxyRequireHeaders() Gets boolean value to indicate if Request has ProxyRequireHeaders Returns: boolean value to indicate if Request has ProxyRequireHeaders

setProxyRequireHeaders public void setProxyRequireHeaders(java.util.List proxyRequireHeaders) throws java.lang.IllegalArgumentException Sets ProxyRequireHeaders of Request. Parameters: proxyRequireHeaders - List of ProxyRequireHeaders to set Throws: java.lang.IllegalArgumentException - if proxyRequireHeaders is null, empty, contains any elements that are null or not ProxyRequireHeaders from the same JAIN SIP implementation

removeProxyRequireHeaders public void removeProxyRequireHeaders() Removes ProxyRequireHeaders from Request (if any exist)

getRequireHeaders public HeaderIterator getRequireHeaders()

Gets HeaderIterator of RequireHeaders of Request. (Returns null if no RequireHeaders exist) Returns: HeaderIterator of RequireHeaders of Request

hasRequireHeaders public boolean hasRequireHeaders() Gets boolean value to indicate if Request has RequireHeaders Returns: boolean value to indicate if Request has RequireHeaders

setRequireHeaders public void setRequireHeaders(java.util.List requireHeaders) throws java.lang.IllegalArgumentException Sets RequireHeaders of Request. Parameters: requireHeaders - List of RequireHeaders to set Throws: java.lang.IllegalArgumentException - if requireHeaders is null, empty, contains any elements that are null or not RequireHeaders from the same JAIN SIP implementation

removeRequireHeaders public void removeRequireHeaders() Removes RequireHeaders from Request (if any exist)

getRouteHeaders public HeaderIterator getRouteHeaders() Gets HeaderIterator of RouteHeaders of Request. (Returns null if no RouteHeaders exist) Returns: HeaderIterator of RouteHeaders of Request

hasRouteHeaders public boolean hasRouteHeaders() Gets boolean value to indicate if Request has RouteHeaders Returns: boolean value to indicate if Request has RouteHeaders

setRouteHeaders public void setRouteHeaders(java.util.List routeHeaders) throws java.lang.IllegalArgumentException Sets RouteHeaders of Request. Parameters: routeHeaders - List of RouteHeaders to set Throws: java.lang.IllegalArgumentException - if routeHeaders is null, empty, contains any elements that are null or not RouteHeaders from the

same JAIN SIP implementation

removeRouteHeaders public void removeRouteHeaders() Removes RouteHeaders from Request (if any exist)

getResponseKeyHeader public ResponseKeyHeader getResponseKeyHeader() throws HeaderParseException Gets ResponseKeyHeader of Request. (Returns null if no ResponseKeyHeader exists) Returns: ResponseKeyHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasResponseKeyHeader public boolean hasResponseKeyHeader() Gets boolean value to indicate if Request has ResponseKeyHeader Returns: boolean value to indicate if Request has ResponseKeyHeader

setResponseKeyHeader public void setResponseKeyHeader(ResponseKeyHeader responseKeyHeader) throws java.lang.IllegalArgumentException Sets ResponseKeyHeader of Request. Parameters: responseKeyHeader - ResponseKeyHeader to set Throws: java.lang.IllegalArgumentException - if responseKeyHeader is null or not from same JAIN SIP implementation

removeResponseKeyHeader public void removeResponseKeyHeader() Removes ResponseKeyHeader from Request (if it exists)

getPriorityHeader public PriorityHeader getPriorityHeader() throws HeaderParseException Gets PriorityHeader of Request. (Returns null if no PriorityHeader exists) Returns: PriorityHeader of Request Throws: HeaderParseException - if implementation cannot parse header value

hasPriorityHeader public boolean hasPriorityHeader() Gets boolean value to indicate if Request has PriorityHeader Returns: boolean value to indicate if Request has PriorityHeader

setPriorityHeader public void setPriorityHeader(PriorityHeader priorityHeader) throws java.lang.IllegalArgumentException Sets PriorityHeader of Request. Parameters: priorityHeader - PriorityHeader to set Throws: java.lang.IllegalArgumentException - if priorityHeader is null or not from same JAIN SIP implementation

removePriorityHeader public void removePriorityHeader() Removes PriorityHeader from Request (if it exists)

getSubjectHeader public SubjectHeader getSubjectHeader() throws HeaderParseException Gets SubjectHeader of InviteMessage. (Returns null if no SubjectHeader exists) Returns: SubjectHeader of InviteMessage Throws: HeaderParseException - if implementation cannot parse header value

hasSubjectHeader public boolean hasSubjectHeader() Gets boolean value to indicate if Request has SubjectHeader Returns: boolean value to indicate if Request has SubjectHeader

setSubjectHeader public void setSubjectHeader(SubjectHeader subjectHeader) throws java.lang.IllegalArgumentException Sets SubjectHeader of InviteMessage. Parameters: subjectHeader - SubjectHeader to set Throws: java.lang.IllegalArgumentException - if subjectHeader is null or not from same JAIN SIP implementation

removeSubjectHeader public void removeSubjectHeader() Removes SubjectHeader from Request (if it exists) If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.message

Interface Response public interface Response extends Message This interface represents a SIP Response message. After receiving and interpreting a Request, the recipient responds with a Response. As well as Headers and a possible body, Responses also contain a Status-Code and a Reason-Phrase. The Status-Code is a 3-digit integer result code that indicates the outcome of the attempt to understand and satisfy the Request. The Reason-Phrase is intended to give a short textual description of the Status-Code. The Status-Code is intended for use by automata, whereas the Reason-Phrase is intended for the human user. The client is not required to examine or display the Reason-Phrase. SIP/2.0 Defines status codes in the following classes: ● 1xx: Informational -- Indicates that the server or proxy contacted is performing some further action and does not yet have a definitive Response. The client should wait for a further Response from the server, and the server should send such a Response without further prompting. A server should send an Informational Response if it expects to take more than 200 ms to obtain a final Response. A server may issue zero or more Informational Responses, with no restriction on their ordering or uniqueness. Note that Informational Responses are not transmitted reliably, that is, they do not cause the client to send an AckMessage. Servers are free to retransmit Informational Responses and clients can inquire about the current state of call processing by re-sending the Request. ● 2xx: Success -- The Request was successful and must terminate a search. ● 3xx: Redirection -- Gives information about the user's new location, or about alternative services that might be able to satisfy the call. They should terminate an existing search, and may cause the initiator to begin a new search if appropriate. Any Redirection Response must not suggest any of the addresses in the ViaHeaders or the ContactHeader of the Request. (Addresses match if their host and port number match.) To avoid forwarding loops, a user agent client or proxy must check whether the address returned by a redirect server equals an address tried earlier. ● 4xx: Client Error -- These are definite failure Responses from a particular server. The client should not retry the same Request without modification (e.g., adding appropriate authorization). However, the same Request to a different server might be successful. ● 5xx: Server Error -- These are failure Responses given when a server itself has erred. They are not definitive failures, and must not terminate a search if other possible locations remain untried. ● 6xx: Global Failure -- Indicates that a server has definitive information about a particular user, not just the particular instance indicated in the Request-URI. All further searches for this user are doomed to failure and pending searches should be terminated. SIP status codes are extensible. SIP applications are not required to understand the meaning of all registered response codes, though such understanding is obviously desirable. However, applications must understand the class of any status code, as indicated by the first digit, and treat any unrecognized status code as being equivalent to the x00 status code of that class, with the exception that an unrecognized status code must not be cached. For example, if a client receives an unrecognized status code of 431, it can safely assume that there was something wrong with its request and treat the Response as if it had received a BAD_REQUEST(400) status code. In such cases, user agents should present to the user the message body returned with the Response, since that message body is likely to include human-readable information which will explain the unusual status. Here is the list of currently defined status codes grouped by class (x00 codes are in bold) : Class

Code ●

INFORMATIONAL (1xx)

● ● ●

SUCCESS (2xx)

● ● ●

REDIRECTION (3xx)

● ● ● ●

TRYING RINGING CALL_IS_BEING_FORWARDED QUEUED OK MULTIPLE_CHOICES MOVED_PERMANENTLY MOVED_TEMPORARILY SEE_OTHER USE_PROXY ALTERNATIVE_SERVICE

● ● ● ● ● ● ● ● ● ● ●

CLIENT_ERROR (4xx)

● ● ● ● ● ● ● ● ● ● ● ● ● ●

SERVER_ERROR (5xx)

● ● ● ● ●

GLOBAL_ERROR (6xx)

● ● ●

BAD_REQUEST UNAUTHORIZED PAYMENT_REQUIRED FORBIDDEN NOT_FOUND METHOD_NOT_ALLOWED NOT_ACCEPTABLE PROXY_AUTHENTICATION_REQUIRED REQUEST_TIMEOUT CONFLICT GONE LENGTH_REQUIRED ENTITY_TOO_LARGE URI_TOO_LARGE UNSUPPORTED_MEDIA_TYPE BAD_EXTENSION TEMPORARILY_NOT_AVAILABLE CALL_LEG_OR_TRANSACTION_DOES_NOT_EXIST LOOP_DETECTED TOO_MANY_HOPS ADDRESS_INCOMPLETE AMBIGUOUS BUSY_HERE INTERNAL_SERVER_ERROR NOT_IMPLEMENTED BAD_GATEWAY SERVICE_UNAVAILABLE GATEWAY_TIME_OUT SIP_VERSION_NOT_SUPPORTED BUSY_EVERYWHERE DECLINE DOES_NOT_EXIST_ANYWHERE NOT_ACCEPTABLE_ANYWHERE

Version: 0.7

Field Summary static int ADDRESS_INCOMPLETE

The server received a Request with a ToHeader address or Request-URI that was incomplete. static int ALTERNATIVE_SERVICE

The call was not successful, but alternative services are possible. static int AMBIGUOUS

The callee address provided in the Request was ambiguous. static int BAD_EXTENSION

The server did not understand the protocol extension specified in a RequireHeader. static int BAD_GATEWAY

The server, while acting as a gateway or proxy, received an invalid Response from the downstream server it accessed in attempting to fulfill the Request.

static int BAD_REQUEST

The Request could not be understood due to malformed syntax. static int BUSY_EVERYWHERE

The callee's end system was contacted successfully but the callee is busy and does not wish to take the call at this time. static int BUSY_HERE

The callee's end system was contacted successfully but the callee is currently not willing or able to take additional calls. static int CALL_IS_BEING_FORWARDED

A proxy server may use this status code to indicate that the call is being forwarded to a different set of destinations. static int CALL_LEG_OR_TRANSACTION_DOES_NOT_EXIST

This status is returned under two conditions: The server received a ByeMessage that does not match any existing call leg or the server received a CancelMessage that does not match any existing transaction. static int CONFLICT

The Request could not be completed due to a conflict with the current state of the resource. static int DECLINE

The callee's machine was successfully contacted but the user explicitly does not wish to or cannot participate. static int DOES_NOT_EXIST_ANYWHERE

The server has authoritative information that the user indicated in the ToHeader of the Request does not exist anywhere. static int ENTITY_TOO_LARGE

The server is refusing to process a Request because the Request entity is larger than the server is willing or able to process. static int FORBIDDEN

The server understood the Request, but is refusing to fulfill it. static int GATEWAY_TIME_OUT

The server, while acting as a gateway, did not receive a timely Response from the server (e.g., a location server) it accessed in attempting to complete the Request. static int GONE

The requested resource is no longer available at the server and no forwarding address is known. static int INTERNAL_SERVER_ERROR

The server encountered an unexpected condition that prevented it from fulfilling the Request. static int LENGTH_REQUIRED

The server refuses to accept the Request without a defined Content- Length. static int LOOP_DETECTED

The server received a Request with a ViaHeader containing itself. static int METHOD_NOT_ALLOWED

The method specified in the Request is not allowed for the address identified by the Request-URI. static int MOVED_PERMANENTLY

The user can no longer be found at the address in the Request-URI and the requesting client should retry at the new address(es) given by the ContactHeader(s). static int MOVED_TEMPORARILY

The requesting client should retry the Request at the new address(es) given by the ContactHeader(s).

static int MULTIPLE_CHOICES

The address in the Request resolved to several choices, each with its own specific location, and the user (or user agent) can select a preferred communication end point and redirect its Request to that location. static int NOT_ACCEPTABLE

The resource identified by the Request is only capable of generating Response entities which have content characteristics not acceptable according to the AcceptHeaders sent in the Request. static int NOT_FOUND

The server has definitive information that the user does not exist at the domain specified in the Request-URI. static int NOT_IMPLEMENTED

The server does not support the functionality required to fulfill the Request. static int OK

The Request has succeeded. static int PAYMENT_REQUIRED

Reserved for future use. static int PROXY_AUTHENTICATION_REQUIRED

This code is similar to UNAUTHORIZED, but indicates that the client must first authenticate itself with the proxy. static int QUEUED

The called party is temporarily unavailable, but the callee has decided to queue the call rather than reject it. static int REQUEST_TIMEOUT

The server could not produce a Response, e.g., a user location, within the time indicated in the ExpiresHeader of the Request. static int RINGING

The called user agent has located a possible location where the user has registered recently and is trying to alert the user. static int SEE_OTHER

See other. static int SERVICE_UNAVAILABLE

The server is currently unable to handle the Request due to a temporary overloading or maintenance of the server. static int SESSION_NOT_ACCEPTABLE

The user's agent was contacted successfully but some aspects of the session description such as the requested media, bandwidth, or addressing style were not acceptable. static int SIP_VERSION_NOT_SUPPORTED

The server does not support, or refuses to support, the SIP protocol version that was used in the Request. static int TEMPORARILY_NOT_AVAILABLE

The callee's end system was contacted successfully but the callee is currently unavailable (e.g., not logged in or logged in in such a manner as to preclude communication with the callee). static int TOO_MANY_HOPS

The server received a Request that contains more ViaHeaders than allowed by the MaxForwardsHeader. static int TRYING

Some unspecified action is being taken on behalf of this call (e.g., a database is being consulted), but the user has not yet been located. static int UNAUTHORIZED

The Request requires user authentication.

static int UNSUPPORTED_MEDIA_TYPE

The server is refusing to service the Request because the message body of the Request is in a format not supported by the requested resource for the requested method. static int URI_TOO_LARGE

The server is refusing to service the Request because the Request-URI is longer than the server is willing to interpret. static int USE_PROXY

The requested resource must be accessed through the proxy given by the ContactHeader.

Method Summary HeaderIterator getAllowHeaders()

Gets HeaderIterator of AllowHeaders of Response. ProxyAuthenticateHeader getProxyAuthenticateHeader()

Gets ProxyAuthenticateHeader of Response. java.lang.String getReasonPhrase()

Gets reason phrase of Response. ServerHeader getServerHeader()

Gets ServerHeader of Response. int getStatusCode()

Gets status code of Response. HeaderIterator getUnsupportedHeaders()

Gets HeaderIterator of UnsupportedHeaders of Response. HeaderIterator getWarningHeaders()

Gets HeaderIterator of WarningHeaders of Response. HeaderIterator getWWWAuthenticateHeaders()

Gets HeaderIterator of WWWAuthenticateHeaders of Response. boolean hasAllowHeaders()

Gets boolean value to indicate if Response has AllowHeaders boolean hasProxyAuthenticateHeader()

Gets boolean value to indicate if Response has ProxyAuthenticateHeader boolean hasServerHeader()

Gets boolean value to indicate if Response has ServerHeader boolean hasUnsupportedHeaders()

Gets boolean value to indicate if Response has UnsupportedHeaders boolean hasWarningHeaders()

Gets boolean value to indicate if Response has WarningHeaders boolean hasWWWAuthenticateHeaders()

Gets boolean value to indicate if Response has WWWAuthenticateHeaders void removeAllowHeaders()

Removes AllowHeaders from Response (if any exist) void removeProxyAuthenticateHeader()

Removes ProxyAuthenticateHeader from Response (if it exists) void removeServerHeader()

Removes ServerHeader from Response (if it exists) void removeUnsupportedHeaders()

Removes UnsupportedHeaders from Response (if any exist) void removeViaHeader()

Removes first ViaHeader from Response's ViaHeaders.

void removeWarningHeaders()

Removes WarningHeaders from Response (if any exist) void removeWWWAuthenticateHeaders()

Removes WWWAuthenticateHeaders from Response (if any exist) void setAllowHeaders(java.util.List allowHeaders)

Sets AllowHeaders of Response. void setProxyAuthenticateHeader(ProxyAuthenticateHeader proxyAuthenticateHeader)

Sets ProxyAuthenticateHeader of Response. void setReasonPhrase(java.lang.String reasonPhrase)

Sets reason phrase of Response. void setServerHeader(ServerHeader serverHeader)

Sets ServerHeader of Response. void setStatusCode(int statusCode)

Sets status code of Response. void setUnsupportedHeaders(java.util.List unsupportedHeaders)

Sets UnsupportedHeaders of Response. void setWarningHeaders(java.util.List warningHeaders)

Sets WarningHeaders of Response. void setWWWAuthenticateHeaders(java.util.List wwwAuthenticateHeaders)

Sets WWWAuthenticateHeaders of Response.

Methods inherited from interface jain.protocol.ip.sip.message.Message addHeader, addHeaders, clone, equals, getAcceptEncodingHeaders, getAcceptHeaders, getAcceptLanguageHeaders, getBodyAsBytes, getBodyAsString, getCallIdHeader, getContactHeaders, getContentEncodingHeaders, getContentLengthHeader, getContentTypeHeader, getCSeqHeader, getDateHeader, getEncryptionHeader, getExpiresHeader, getFromHeader, getHeader, getHeaders, getHeaders, getOrganizationHeader, getRecordRouteHeaders, getRetryAfterHeader, getStartLine, getTimeStampHeader, getToHeader, getUserAgentHeader, getVersionMajor, getVersionMinor, getViaHeaders, hasAcceptEncodingHeaders, hasAcceptHeaders, hasAcceptLanguageHeaders, hasBody, hasContactHeaders, hasContentEncodingHeaders, hasContentLengthHeader, hasContentTypeHeader, hasDateHeader, hasEncryptionHeader, hasExpiresHeader, hasHeaders, hasHeaders, hasOrganizationHeader, hasRecordRouteHeaders, hasRetryAfterHeader, hasTimeStampHeader, hasUserAgentHeader, hasViaHeaders, isRequest, removeAcceptEncodingHeaders, removeAcceptHeaders, removeAcceptLanguageHeaders, removeBody, removeContactHeaders, removeContentEncodingHeaders, removeContentLengthHeader, removeContentTypeHeader, removeDateHeader, removeEncryptionHeader, removeExpiresHeader, removeHeader, removeHeaders, removeOrganizationHeader, removeRecordRouteHeaders, removeRetryAfterHeader, removeTimeStampHeader, removeUserAgentHeader, removeViaHeaders, setAcceptEncodingHeaders, setAcceptHeaders, setAcceptLanguageHeaders, setBody, setBody, setCallIdHeader, setContactHeaders, setContentEncodingHeaders, setContentLengthHeader, setContentTypeHeader, setCSeqHeader, setDateHeader, setEncryptionHeader, setExpiresHeader, setFromHeader, setHeader, setHeaders, setOrganizationHeader, setRecordRouteHeaders, setRetryAfterHeader, setTimeStampHeader, setToHeader, setUserAgentHeader, setVersion, setViaHeaders, toString

Field Detail TRYING public static final int TRYING Some unspecified action is being taken on behalf of this call (e.g., a database is being consulted), but the user has not yet been located.

RINGING public static final int RINGING The called user agent has located a possible location where the user has registered recently and is trying to alert the user.

CALL_IS_BEING_FORWARDED public static final int CALL_IS_BEING_FORWARDED A proxy server may use this status code to indicate that the call is being forwarded to a different set of destinations.

QUEUED public static final int QUEUED The called party is temporarily unavailable, but the callee has decided to queue the call rather than reject it. When the callee becomes available, it will return the appropriate final status Response. The reason phrase may give further details about the status of the call, e.g., "5 calls queued; expected waiting time is 15 minutes". The server may issue several QUEUED Responses to update the caller about the status of the queued call.

OK public static final int OK The Request has succeeded. The information returned with the Response depends on the method used in the Request, for example: ● BYE: The call has been terminated. The message body is empty. ● CANCEL: The search has been cancelled. The message body is empty. ● INVITE: The callee has agreed to participate; the message body indicates the callee's capabilities. ● OPTIONS: The callee has agreed to share its capabilities, included in the message body. ● REGISTER: The registration has succeeded. The client treats the message body according to the ContentTypeHeader.

MULTIPLE_CHOICES public static final int MULTIPLE_CHOICES The address in the Request resolved to several choices, each with its own specific location, and the user (or user agent) can select a preferred communication end point and redirect its Request to that location. The Response should include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate, if allowed by the AcceptHeader. The entity format is specified by the media type given in the ContentTypeHeader. The choices should also be listed as ContactHeaders. Unlike HTTP, the SIP Response may contain several ContactHeaders. User agents may use the ContactHeader values for automatic redirection or may ask the user to confirm a choice. However, the SIP specification does not define any standard for such automatic selection. This status code is appropriate if the callee can be reached at several different locations and the server cannot or prefers not to proxy the Request.

MOVED_PERMANENTLY public static final int MOVED_PERMANENTLY The user can no longer be found at the address in the Request-URI and the requesting client should retry at the new address(es) given by the ContactHeader(s). The caller should update any local directories, address books and user location caches with this new value and redirect future Requests to the address(es) listed.

MOVED_TEMPORARILY public static final int MOVED_TEMPORARILY The requesting client should retry the Request at the new address(es) given by the ContactHeader(s). The duration of the redirection can be indicated through an ExpiresHeader. If there is no explicit expiration time, the address is only valid for this call and must not be cached for future calls.

SEE_OTHER public static final int SEE_OTHER See other.

USE_PROXY public static final int USE_PROXY The requested resource must be accessed through the proxy given by the ContactHeader. The ContactHeader gives the URI of the proxy. The recipient is expected to repeat this single Request via the proxy. USE_PROXY Responses must only be generated by user agent servers.

ALTERNATIVE_SERVICE public static final int ALTERNATIVE_SERVICE The call was not successful, but alternative services are possible. The alternative services are described in the message body of the Response. Formats for such bodies are not defined in RFC 2543, and may be he subject of future standardization.

BAD_REQUEST public static final int BAD_REQUEST The Request could not be understood due to malformed syntax.

UNAUTHORIZED public static final int UNAUTHORIZED The Request requires user authentication.

PAYMENT_REQUIRED public static final int PAYMENT_REQUIRED Reserved for future use.

FORBIDDEN public static final int FORBIDDEN The server understood the Request, but is refusing to fulfill it. Authorization will not help, and the Request should not be repeated.

NOT_FOUND public static final int NOT_FOUND The server has definitive information that the user does not exist at the domain specified in the Request-URI. This status is also returned if the domain in the Request-URI does not match any of the domains handled by the recipient of the Request.

METHOD_NOT_ALLOWED public static final int METHOD_NOT_ALLOWED The method specified in the Request is not allowed for the address identified by the Request-URI. The Response must include AllowHeaders containing a valid methods for the indicated address.

NOT_ACCEPTABLE public static final int NOT_ACCEPTABLE The resource identified by the Request is only capable of generating Response entities which have content characteristics not acceptable according to the AcceptHeaders sent in the Request.

PROXY_AUTHENTICATION_REQUIRED public static final int PROXY_AUTHENTICATION_REQUIRED This code is similar to UNAUTHORIZED, but indicates that the client must first authenticate itself with the proxy. The proxy must return a ProxyAuthenticateHeader containing a challenge applicable to the proxy for the requested resource. The client may repeat the Request with a suitable ProxyAuthorizationHeader. This status code is used for applications where access to the communication channel (e.g., a telephony gateway) rather than the callee requires authentication.

REQUEST_TIMEOUT public static final int REQUEST_TIMEOUT The server could not produce a Response, e.g., a user location, within the time indicated in the ExpiresHeader of the Request. The client may repeat the Request without modifications at any later time.

CONFLICT public static final int CONFLICT The Request could not be completed due to a conflict with the current state of the resource. This status code is returned if the action parameter in a RegisterMessage conflicts with existing registrations.

GONE public static final int GONE The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code

NOT_FOUND should be used instead.

LENGTH_REQUIRED public static final int LENGTH_REQUIRED The server refuses to accept the Request without a defined Content- Length. The client may repeat the Request if it adds a valid ContentLengthHeader containing the length of the message-body in the Request.

ENTITY_TOO_LARGE public static final int ENTITY_TOO_LARGE The server is refusing to process a Request because the Request entity is larger than the server is willing or able to process. The server may close the connection to prevent the client from continuing the Request. If the condition is temporary, the server should include a RetryAfterHeader to indicate that it is temporary and after what time the client may try again.

URI_TOO_LARGE public static final int URI_TOO_LARGE The server is refusing to service the Request because the Request-URI is longer than the server is willing to interpret.

UNSUPPORTED_MEDIA_TYPE public static final int UNSUPPORTED_MEDIA_TYPE The server is refusing to service the Request because the message body of the Request is in a format not supported by the requested resource for the requested method. The server should return a list of acceptable formats using AcceptHeaders, AcceptEncodingHeaders and AcceptLanguageHeaders.

BAD_EXTENSION public static final int BAD_EXTENSION The server did not understand the protocol extension specified in a RequireHeader.

TEMPORARILY_NOT_AVAILABLE public static final int TEMPORARILY_NOT_AVAILABLE The callee's end system was contacted successfully but the callee is currently unavailable (e.g., not logged in or logged in in such a manner as to preclude communication with the callee). The Response may indicate a better time to call in the RetryAfterHeader. The user could also be available elsewhere (unbeknownst to this host), thus, this Response does not terminate any searches. The reason phrase should indicate a more precise cause as to why the callee is unavailable. This value should be setable by the user agent. Status BUSY_HERE may be used to more precisely indicate a particular reason for the call failure. This status is also returned by a redirect server that recognizes the user identified by the Request-URI, but does not currently have a valid forwarding location for that user.

CALL_LEG_OR_TRANSACTION_DOES_NOT_EXIST public static final int CALL_LEG_OR_TRANSACTION_DOES_NOT_EXIST This status is returned under two conditions: The server received a ByeMessage that does not match any existing call leg or the server received a CancelMessage that does not match any existing transaction. (A server simply discards an AckMessage referring to an unknown transaction.)

LOOP_DETECTED public static final int LOOP_DETECTED The server received a Request with a ViaHeader containing itself.

TOO_MANY_HOPS public static final int TOO_MANY_HOPS The server received a Request that contains more ViaHeaders than allowed by the MaxForwardsHeader.

ADDRESS_INCOMPLETE public static final int ADDRESS_INCOMPLETE The server received a Request with a ToHeader address or Request-URI that was incomplete. Additional information should be provided. This status code allows overlapped dialing. With overlapped dialing, the client does not know the length of the dialing string. It sends strings of increasing lengths, prompting the user for more input, until it no longer receives an ADDRESS_INCOMPLETE status response.

AMBIGUOUS public static final int AMBIGUOUS The callee address provided in the Request was ambiguous. The Response may contain a listing of possible unambiguous addresses in ContactHeaders. Revealing alternatives can infringe on privacy concerns of the user or the organization. It must be possible to configure a server to respond with status NOT_FOUND or to suppress the listing of possible choices if the Request address was ambiguous. Some email and voice mail systems provide this functionality. A status code separate from Redirect status codes is used since the semantics are different: for MULTIPLE_CHOICES, it is assumed that the same person or service will be reached by the choices provided. While an automated choice or sequential search makes sense for a Redirect Response, user intervention is required for an AMBIGUOUS response.

BUSY_HERE public static final int BUSY_HERE The callee's end system was contacted successfully but the callee is currently not willing or able to take additional calls. The Response may indicate a better time to call in the RetryAfterHeader. The user could also be available elsewhere, such as through a voice mail service, thus, this Response does not terminate any searches. Status BUSY_EVERYWHERE should be used if the server knows that no other end system will be able to accept this call.

INTERNAL_SERVER_ERROR public static final int INTERNAL_SERVER_ERROR The server encountered an unexpected condition that prevented it from fulfilling the Request. The client may display the specific error condition, and may retry the Request after several seconds.

NOT_IMPLEMENTED public static final int NOT_IMPLEMENTED The server does not support the functionality required to fulfill the Request. This is the appropriate Response when the server does not recognize the Request method and is not capable of supporting it for any user.

BAD_GATEWAY public static final int BAD_GATEWAY The server, while acting as a gateway or proxy, received an invalid Response from the downstream server it accessed in attempting to fulfill the Request.

SERVICE_UNAVAILABLE public static final int SERVICE_UNAVAILABLE The server is currently unable to handle the Request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay may be indicated in a RetryAfterHeader. If no RetryAfterHeader is given, the client must handle the response as it would for an INTERNAL_SERVER_ERROR Response. Note: The existence of the SERVICE_UNAVAILABLE status code does not imply that a server has to use it when becoming overloaded. Some servers may wish to simply refuse the connection.

GATEWAY_TIME_OUT public static final int GATEWAY_TIME_OUT The server, while acting as a gateway, did not receive a timely Response from the server (e.g., a location server) it accessed in attempting to complete the Request.

SIP_VERSION_NOT_SUPPORTED public static final int SIP_VERSION_NOT_SUPPORTED The server does not support, or refuses to support, the SIP protocol version that was used in the Request. The server is indicating that it is unable or unwilling to complete the Request using the same major version as the client, other than with this error message. The Response may contain an entity describing why that version is not supported and what other protocols are supported by that server. The format for such an entity is not defined in RFC 2543 and may be the subject of future standardization.

BUSY_EVERYWHERE public static final int BUSY_EVERYWHERE The callee's end system was contacted successfully but the callee is busy and does not wish to take the call at this time. The Response may indicate a better time to call in the RetryAfterHeader. If the callee does not wish to reveal the reason for declining the call, the callee uses status code DECLINE instead. This status code is returned only if the client knows that no other end point (such as a voice mail system) will answer the Request. Otherwise, BUSY_HERE should be returned.

DECLINE public static final int DECLINE The callee's machine was successfully contacted but the user explicitly does not wish to or cannot participate. The Response may indicate a better time to call in the RetryAfterHeader.

DOES_NOT_EXIST_ANYWHERE public static final int DOES_NOT_EXIST_ANYWHERE The server has authoritative information that the user indicated in the ToHeader of the Request does not exist anywhere. Searching for the user elsewhere will not yield any results.

SESSION_NOT_ACCEPTABLE public static final int SESSION_NOT_ACCEPTABLE The user's agent was contacted successfully but some aspects of the session description such as the requested media, bandwidth, or addressing style were not acceptable. A SESSION_NOT_ACCEPTABLE response means that the user wishes to communicate, but cannot adequately support the session described. The SESSION_NOT_ACCEPTABLE Response may contain a list of reasons in a WarningHeader describing why the session described cannot be supported. It is hoped that negotiation will not frequently be needed, and when a new user is being invited to join an already existing conference, negotiation may not be possible. It is up to the invitation initiator to decide whether or not to act on a SESSION_NOT_ACCEPTABLE Response.

Method Detail removeViaHeader public void removeViaHeader() Removes first ViaHeader from Response's ViaHeaders.

getAllowHeaders public HeaderIterator getAllowHeaders() Gets HeaderIterator of AllowHeaders of Response. (Returns null if no AllowHeaders exist) Returns: HeaderIterator of AllowHeaders of Response

hasAllowHeaders public boolean hasAllowHeaders() Gets boolean value to indicate if Response has AllowHeaders Returns: boolean value to indicate if Response has AllowHeaders

setAllowHeaders public void setAllowHeaders(java.util.List allowHeaders) throws java.lang.IllegalArgumentException Sets AllowHeaders of Response. Parameters: allowHeaders - List of AllowHeaders to set Throws: java.lang.IllegalArgumentException - if allowHeaders is null, empty, contains any elements that are null or not AllowHeaders from the same JAIN SIP implementation

removeAllowHeaders public void removeAllowHeaders() Removes AllowHeaders from Response (if any exist)

getProxyAuthenticateHeader public ProxyAuthenticateHeader getProxyAuthenticateHeader() throws HeaderParseException Gets ProxyAuthenticateHeader of Response. (Returns null if no ProxyAuthenticateHeader exists) Returns: HideHeader of Response Throws: HeaderParseException - if implementation cannot parse header value

hasProxyAuthenticateHeader public boolean hasProxyAuthenticateHeader() Gets boolean value to indicate if Response has ProxyAuthenticateHeader Returns: boolean value to indicate if Response has ProxyAuthenticateHeader

removeProxyAuthenticateHeader public void removeProxyAuthenticateHeader() Removes ProxyAuthenticateHeader from Response (if it exists)

setProxyAuthenticateHeader public void setProxyAuthenticateHeader(ProxyAuthenticateHeader proxyAuthenticateHeader) throws java.lang.IllegalArgumentException Sets ProxyAuthenticateHeader of Response. Parameters: ProxyAuthenticateHeader - ProxyAuthenticateHeader to set Throws: java.lang.IllegalArgumentException - if proxyAuthenticateHeader is null or not from same JAIN SIP implementation

getWWWAuthenticateHeaders public HeaderIterator getWWWAuthenticateHeaders() Gets HeaderIterator of WWWAuthenticateHeaders of Response. (Returns null if no WWWAuthenticateHeaders exist) Returns: HeaderIterator of WWWAuthenticateHeaders of Response

hasWWWAuthenticateHeaders public boolean hasWWWAuthenticateHeaders() Gets boolean value to indicate if Response has WWWAuthenticateHeaders Returns: boolean value to indicate if Response has WWWAuthenticateHeaders

removeWWWAuthenticateHeaders public void removeWWWAuthenticateHeaders() Removes WWWAuthenticateHeaders from Response (if any exist)

setWWWAuthenticateHeaders public void setWWWAuthenticateHeaders(java.util.List wwwAuthenticateHeaders) throws java.lang.IllegalArgumentException Sets WWWAuthenticateHeaders of Response. Parameters: wwwAuthenticateHeaders - List of WWWAuthenticateHeaders to set Throws: java.lang.IllegalArgumentException - if wwwAuthenticateHeaders is null, empty, contains any elements that are null or not WWWAuthenticateHeaders from the same JAIN SIP implementation

getServerHeader public ServerHeader getServerHeader() throws HeaderParseException Gets ServerHeader of Response. (Returns null if no ServerHeader exists) Returns: ServerHeader of Response Throws: HeaderParseException - if implementation cannot parse header value

hasServerHeader public boolean hasServerHeader() Gets boolean value to indicate if Response has ServerHeader Returns: boolean value to indicate if Response has ServerHeader

removeServerHeader public void removeServerHeader() Removes ServerHeader from Response (if it exists)

setServerHeader public void setServerHeader(ServerHeader serverHeader) throws java.lang.IllegalArgumentException Sets ServerHeader of Response. Parameters: serverHeader - ServerHeader to set Throws: java.lang.IllegalArgumentException - if serverHeader is null or not from same JAIN SIP implementation

getUnsupportedHeaders public HeaderIterator getUnsupportedHeaders() Gets HeaderIterator of UnsupportedHeaders of Response. (Returns null if no UnsupportedHeaders exist) Returns: HeaderIterator of UnsupportedHeaders of Response

hasUnsupportedHeaders public boolean hasUnsupportedHeaders() Gets boolean value to indicate if Response has UnsupportedHeaders Returns: boolean value to indicate if Response has UnsupportedHeaders

removeUnsupportedHeaders public void removeUnsupportedHeaders() Removes UnsupportedHeaders from Response (if any exist)

setUnsupportedHeaders public void setUnsupportedHeaders(java.util.List unsupportedHeaders) throws java.lang.IllegalArgumentException Sets UnsupportedHeaders of Response. Parameters: unsupportedHeaders - List of UnsupportedHeaders to set Throws: java.lang.IllegalArgumentException - if unsupportedHeaders is null, empty, contains any elements that are null or not UnsupportedHeaders from the same JAIN SIP implementation

getWarningHeaders public HeaderIterator getWarningHeaders() Gets HeaderIterator of WarningHeaders of Response. (Returns null if no WarningHeaders exist) Returns: HeaderIterator of WarningHeaders of Response

hasWarningHeaders public boolean hasWarningHeaders() Gets boolean value to indicate if Response has WarningHeaders Returns: boolean value to indicate if Response has WarningHeaders

removeWarningHeaders public void removeWarningHeaders() Removes WarningHeaders from Response (if any exist)

setWarningHeaders public void setWarningHeaders(java.util.List warningHeaders) throws java.lang.IllegalArgumentException Sets WarningHeaders of Response. Parameters: warningHeaders - List of WarningHeaders to set Throws: java.lang.IllegalArgumentException - if warningHeaders is null, empty, contains any elements that are null or not WarningHeaders from the same JAIN SIP implementation

getStatusCode public int getStatusCode() throws SipParseException Gets status code of Response. Returns: status code of Response Throws: SipParseException - if implementation cannot parse status code

setStatusCode public void setStatusCode(int statusCode) throws SipParseException Sets status code of Response. Parameters: statusCode - status code to set Throws: SipParseException - if statusCode is not accepted by implementation

getReasonPhrase public java.lang.String getReasonPhrase() throws SipParseException Gets reason phrase of Response. Returns: reason phrase of Response Throws: SipParseException - if implementation cannot parse reason phrase

setReasonPhrase public void setReasonPhrase(java.lang.String reasonPhrase) throws java.lang.IllegalArgumentException, SipParseException Sets reason phrase of Response. Parameters: reasonPhrase - reason phrase to set Throws: java.lang.IllegalArgumentException - if reasonPhrase is null SipParseException - if reasonPhrase is not accepted by implementation If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

jain.protocol.ip.sip.message Interfaces Message MessageFactory Request Response

Serialized Form Package jain.protocol.ip.sip Class jain.protocol.ip.sip.ListeningPointUnavailableException implements Serializable Class jain.protocol.ip.sip.SipException implements Serializable Class jain.protocol.ip.sip.SipListenerAlreadyRegisteredException implements Serializable Class jain.protocol.ip.sip.SipListenerNotRegisteredException implements Serializable Class jain.protocol.ip.sip.SipParseException implements Serializable Serialized Fields unparsable java.lang.String unparsable

Class jain.protocol.ip.sip.SipPeerUnavailableException implements Serializable

Class jain.protocol.ip.sip.TransactionDoesNotExistException implements Serializable Class jain.protocol.ip.sip.UnableToDeleteProviderException implements Serializable Package jain.protocol.ip.sip.header Class jain.protocol.ip.sip.header.HeaderParseException implements Serializable Serialized Fields header Header header If you have any comments or queries, please mail them to [email protected] Copyright - 2000 Sun Microsystems

All Classes AcceptEncodingHeader AcceptHeader AcceptLanguageHeader AddressFactory AllowHeader AuthorizationHeader CallIdHeader ContactHeader ContentEncodingHeader ContentLengthHeader ContentTypeHeader CSeqHeader DateHeader EncodingHeader EncryptionHeader EndPointHeader ExpiresHeader FromHeader Header HeaderFactory HeaderIterator HeaderParseException HideHeader ListeningPoint ListeningPointUnavailableException MaxForwardsHeader Message MessageFactory NameAddress NameAddressHeader OptionTagHeader OrganizationHeader Parameters ParametersHeader PriorityHeader ProductHeader ProxyAuthenticateHeader ProxyAuthorizationHeader ProxyRequireHeader

RecordRouteHeader Request RequireHeader Response ResponseKeyHeader RetryAfterHeader RouteHeader SecurityHeader ServerHeader SipException SipFactory SipListener SipListenerAlreadyRegisteredException SipListenerNotRegisteredException SipParseException SipPeerUnavailableException SipProvider SipStack SipURL SubjectHeader TimeStampHeader ToHeader TransactionDoesNotExistException UnableToDeleteProviderException UnsupportedHeader URI UserAgentHeader ViaHeader WarningHeader WWWAuthenticateHeader