SipURI Interface

The SipURI interface represents sip and sips URIs. These URIs resemble email addresses in their format, appearing as user@host, where the user can be a username or a telephone number, and the host can be a domain name, a numeric IP address, or a hostname. In addition to the basic format, SipURI objects can include parameters and headers, though headers are not valid in all contexts. While syntactically identical, sip and sips URIs differ in semantics; the sips scheme specifies that the resource must be contacted securely using TLS, ensuring secure communications from the UAC to the domain and beyond, depending on the domain's policies. This distinction allows any sip URI to be "upgraded" to a sips URI for secure communication, as per RFC 3261. The SipURI interface abstracts both types of URIs due to their similar usage and syntax. It ensures that escaped characters in the string representation of these URIs are unescaped before they are presented to servlets, and any reserved or excluded characters in values passed to setter methods are properly escaped by the SIP servlet container.

Methods:

getUser

java.lang.String getUser()

The getUser method retrieves the user part of this SipURI. The user part typically represents the username or identifier before the @ symbol in a SIP URI.
Returns: A String containing the user part of this SipURI. If no user part exists, it returns null.

setUser

void setUser(java.lang.String user)

The setUser method assigns a new user part to this SipURI. The user part represents the identifier or username in the SIP URI. If the provided user is null, it removes the existing user part.
Parameters:
user: A String specifying the new user part for this SipURI.

getUserPassword

java.lang.String getUserPassword()

The getUserPassword method retrieves the password associated with this SipURI. If no password is set, the method returns null. This password is part of the user credentials in the URI, but it is optional.
Returns:
A String representing the password of this SipURI, or null if no password is defined.

setUserPassword

void setUserPassword(java.lang.String password)

The setUserPassword method sets the password associated with this SipURI. While this method allows specifying a password for the URI, it is discouraged due to the security risk of transmitting passwords in clear text.
Parameters:
password: A String representing the new password for this SipURI.

getHost

java.lang.String getHost()

The getHost method retrieves the host component of this SipURI. The host represents the domain name, hostname, or IP address specified in the URI.
Returns:
A String containing the host part of this SipURI.

setHost

void setHost(java.lang.String host)

The setHost method updates the host component of this SipURI. The host should be specified as a fully qualified domain name or a numeric IP address.
Parameters:
host: A String representing the new host name to set for this SipURI.

getPort

int getPort()

The getPort method retrieves the port number associated with this SipURI. If the port number is not explicitly set, the method returns -1.
Returns: The port number of this SipURI, or -1 if no port is set.

setPort

void setPort(int port)

The setPort method assigns a new port number to this SipURI. A negative value indicates that the port number is not set, and subsequent calls to getPort() will return -1.
Parameters:
port: The new port number. Use a negative value to unset the port.

isSecure

boolean isSecure()

The isSecure method checks whether this SipURI represents a secure URI (sips) or a non-secure URI (sip).
Returns: true if this SipURI represents a sips URI. false if it represents a standard sip URI.

setSecure

void setSecure(boolean b)

The setSecure method sets the scheme of this SipURI to either sip or sips based on the provided parameter.
Parameters:
b: A boolean value. If true, the scheme is set to sips (secure). If false, the scheme is set to sip (non-secure).

getTransportParam

java.lang.String getTransportParam()

The getTransportParam method retrieves the value of the "transport" parameter associated with this SipURI. If the "transport" parameter is not set, the method returns null.
Returns: A String containing the value of the "transport" parameter, or null if it is not set.

setTransportParam

void setTransportParam(java.lang.String transport)

The setTransportParam method sets the value of the "transport" parameter for this SipURI. This parameter indicates the transport protocol to be used for sending requests and responses to the entity identified by this URI. Standard values include "udp", "tcp", "sctp", and "tls", but other custom values may also be specified.
This method is functionally equivalent to calling setParameter("transport", transport).
Parameters:
transport: A String specifying the new value for the "transport" parameter.

getMAddrParam

java.lang.String getMAddrParam()

The getMAddrParam method retrieves the value of the "maddr" parameter for this SipURI. The "maddr" parameter specifies the multicast address to be used for this URI.
This method is equivalent to calling getParameter("maddr").
Returns: A String representing the value of the "maddr" parameter, or null if the parameter is not set.

setMAddrParam

void setMAddrParam(java.lang.String maddr)

The setMAddrParam method assigns a value to the "maddr" parameter for this SipURI. The "maddr" parameter specifies the multicast address to be used.
This method is equivalent to calling setParameter("maddr", maddr).
Parameters:
maddr (String): The new value for the "maddr" parameter.

getMethodParam

java.lang.String getMethodParam()

The getMethodParam method retrieves the value of the "method" parameter from this SipURI. The "method" parameter specifies the SIP method to be used when this URI is referenced.
Returns: A String representing the value of the "method" parameter, or null if the parameter is not set.

setMethodParam

void setMethodParam(java.lang.String method)

The setMethodParam method assigns a new value to the "method" parameter of this SipURI. This parameter specifies the SIP method that should be used for requests targeting this URI.
This method is functionally equivalent to calling setParameter("method", method).
Parameters:
method: A String representing the new value for the "method" parameter.

getTTLParam

int getTTLParam()

The getTTLParam method retrieves the value of the "ttl" (Time-To-Live) parameter from this SipURI. If the parameter is not set, the method returns -1.
This method is functionally equivalent to calling getParameter("ttl").
Returns:
An int representing the value of the "ttl" parameter, or -1 if the parameter is not set.

setTTLParam

void setTTLParam(int ttl)

The setTTLParam method sets the value of the "ttl" (Time-To-Live) parameter for this SipURI. This parameter specifies the TTL value used when packets are sent using UDP multicast.
This method is equivalent to calling setParameter("ttl", ttl).
Parameters:
ttl: An integer representing the new value of the "ttl" parameter.

getUserParam

java.lang.String getUserParam()

The getUserParam method retrieves the value of the "user" parameter from this SipURI. If the parameter is not set, it returns null. The "user" parameter specifies the user type (e.g., "phone" or "ip").
This method is functionally equivalent to calling getParameter("user").
Returns: A String representing the value of the "user" parameter, or null if the parameter is not set.

setUserParam

void setUserParam(java.lang.String user)

The setUserParam method sets the value of the "user" parameter for this SipURI. This parameter specifies the type of user (e.g., "phone" or "ip").
This method is equivalent to calling setParameter("user", user).
Parameters:
user (String): The new value for the "user" parameter.

getLrParam

boolean getLrParam()

The getLrParam method checks whether the "lr" (loose routing) flag parameter is set for this SipURI.
This method is equivalent to evaluating "".equals(getParameter("lr")).
Returns:
true: If the "lr" flag parameter is set.
false: Otherwise.

setLrParam

void setLrParam(boolean flag)

The setLrParam method is used to set or remove the "lr" (loose routing) flag parameter for this SipURI.
Parameters:
flag (boolean). If true, the "lr" flag parameter is added to the SipURI. If false, the "lr" flag parameter is removed from the SipURI.

getHeader

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

The getHeader method retrieves the value of a specified header from the SipURI.
This method allows access to custom or standard headers specified within the SipURI.
Parameters:
name (java.lang.String): The name of the header to retrieve.
Returns: A String representing the value of the specified header. For example, for the URI sip:joe@example.com?Priority=emergency, calling getHeader("Priority") would return "emergency".
Throws:
java.lang.NullPointerException: If the name parameter is null.

setHeader

void setHeader(java.lang.String name,
               java.lang.String value)

The setHeader method assigns a value to a specified header in the SipURI. This method allows modification or addition of headers in the SipURI, enabling customization of SIP communication for specific requirements.
Parameters:
name (java.lang.String): The name of the header to set.
value (java.lang.String): The value to assign to the specified header.

removeHeader

void removeHeader(java.lang.String name)

The removeHeader method deletes a specific header from the SipURI. If the header does not exist, the method performs no action. It is useful for cleaning up or modifying a SipURI by removing unnecessary or outdated headers.
Parameters:
name (java.lang.String): The name of the header to be removed.

getHeaderNames

java.util.Iterator<java.lang.String> getHeaderNames()

The getHeaderNames method provides an Iterator that lists all the header names currently present in the SipURI. It is useful for enumerating headers when working with a SipURI that contains multiple header parameters.
Returns:
java.util.Iterator<java.lang.String>: An Iterator containing the names of all headers defined in the SipURI.

toString

java.lang.String toString()

The toString method provides the string representation of this SipURI. Reserved characters in the URI are escaped as per the requirements of RFC 2396.
Specified by:
toString in interface URI
Overrides:
toString in class java.lang.Object
Returns:
java.lang.String – a string representation of the SipURI.

equals

boolean equals(java.lang.Object o)

The equals method compares the given SipURI with this SipURI using the rules defined in Section 19.1.4 of RFC 3261.
Specified by:
equals in interface URI
Overrides:
equals in class java.lang.Object
Parameters:
o (java.lang.Object): The URI to compare with this SipURI.
Returns: Boolean value. true if the two SipURIs are considered equal according to the comparison rules in RFC 3261, otherwise false.