| javax.sip.header.ContactHeader
| ContactHeader | | public interface ContactHeader extends HeaderAddress,Parameters,Header(Code) | | A Contact header field value provides a URI whose meaning depends on
the type of request or response it is in. A Contact header field value
can contain a display name, a URI with URI parameters, and header
parameters.
The Contact header field provides a SIP or SIPS URI that can be used
to contact that specific instance of the User Agent for subsequent requests.
The Contact header field MUST be present and contain exactly one SIP
or SIPS URI in any request that can result in the establishment of a
dialog. For the methods defined in this specification, that includes
only the INVITE request. For these requests, the scope of the
Contact is global. That is, the Contact header field value contains
the URI at which the User Agent would like to receive requests, and this URI
MUST be valid even if used in subsequent requests outside of any
dialogs.
If the Request-URI or top Route header field value contains a SIPS URI, the
Contact header field MUST contain a SIPS URI as well.
Messages and Contact Headers
- Requests: A contact header is mandatory for INVITE's and optional for
ACK, OPTIONS and REGISTER requests. This allows the callee to send future
Requests, such as BYE Requests, directly to the caller instead of through a
series of proxies.
- Informational Responses - A contact header is optional in a Informational
Response to an INVITE request. It has the same semantics in an Informational
Response as a Success Response.
- Success Responses - A contact header is mandatory in response to INVITE's
and optional in response to OPTIONS and REGISTER requests. An user agent
server sending a Success Response to an INIVTE must insert a ContactHeader
in the Response indicating the SIP address under which it is reachable most
directly for future SIP Requests.
- Redirection Responses - A contact header is optional in response to
INVITE's, OPTIONS, REGISTER and BYE requests. A proxy may also delete the
contact header.
- Ambiguous Header: - A contact header is optional in response to
INVITE, OPTIONS, REGISTER and BYE requests.
The ContactHeader defines the Contact parameters "q" and "expires".
The q-value value is used to prioritize addresses in a
list of contact addresses. The expires value suggests an
expiration interval that indicates how long the client would like a
registration to be valid for a specific address. These parameters are only
used when the Contact is present in a:
- REGISTER request
- REGISTER response
- 3xx response
For Example:
Contact: "Mr. Watson" sip:watson@worcester.jcp.org;
q=0.7; expires=3600, "Mr. Watson" mailto:watson@jcp.org.com; q=0.1
See Also: HeaderAddress
See Also: Parameters
author:
BEA Systems, NIST
version:
1.2 |
| Method Summary | |
| public int | getExpires()
Returns the value of the expires parameter or -1 if no
expires parameter was specified or if the parameter value cannot be
parsed as an int. | | public float | getQValue()
Returns the value of the q-value parameter of this
ContactHeader. | | public boolean | isWildCard()
Returns a boolean value that indicates if the contact header
has the format of Contact: *. | | public void | setExpires(int expires)
Sets the value of the expires parameter as delta-seconds.
When a client sends a REGISTER request, it MAY suggest an expiration
interval that indicates how long the client would like the registration
to be valid for a specific address. | | public void | setQValue(float qValue)
Sets the qValue value of the Name Address. | | public void | setWildCard()
Sets a wildcard on this contact address that is "*" is assigned to the
contact header so that the header will have the format of Contact: *. |
| NAME | | final public static String NAME(Code) | | Name of ContactHeader
|
| getExpires | | public int getExpires()(Code) | | Returns the value of the expires parameter or -1 if no
expires parameter was specified or if the parameter value cannot be
parsed as an int.
value of the expires parameter measured indelta-seconds, O implies removal of Registration specified in Contact Header. |
| getQValue | | public float getQValue()(Code) | | Returns the value of the q-value parameter of this
ContactHeader. The q-value parameter indicates the relative
preference amongst a set of locations. q-values are
decimal numbers from 0 to 1, with higher values indicating higher
preference.
the q-value parameter of this ContactHeader, -1 ifthe q-value is not set. |
| isWildCard | | public boolean isWildCard()(Code) | | Returns a boolean value that indicates if the contact header
has the format of Contact: *.
true if this is a wildcard address, false otherwise.
since:
v1.2 |
| setExpires | | public void setExpires(int expires) throws InvalidArgumentException(Code) | | Sets the value of the expires parameter as delta-seconds.
When a client sends a REGISTER request, it MAY suggest an expiration
interval that indicates how long the client would like the registration
to be valid for a specific address. There are two ways in which a client
can suggest an expiration interval for a binding:
- through an Expires header field
- an "expires" Contact header parameter.
The latter allows expiration intervals to be suggested on a per-binding
basis when more than one binding is given in a single REGISTER request,
whereas the former suggests an expiration interval for all Contact
header field values that do not contain the "expires" parameter. If
neither mechanism for expressing a suggested expiration time is present
in a REGISTER, the client is indicating its desire for the server to
choose.
A User Agent requests the immediate removal of a binding by specifying an
expiration interval of "0" for that contact address in a REGISTER
request. User Agents SHOULD support this mechanism so that bindings can be
removed before their expiration interval has passed. The
REGISTER-specific Contact header field value of "*" applies to all
registrations, but it MUST NOT be used unless the Expires header
field is present with a value of "0". The "*" value can be determined
if "this.getNameAddress().isWildcard() = = true".
Parameters:
expires - new relative value of the expires parameter.0 implies removal of Registration specified in Contact Header.
throws:
InvalidArgumentException - if supplied value is less than zero. |
| setQValue | | public void setQValue(float qValue) throws InvalidArgumentException(Code) | | Sets the qValue value of the Name Address. If more than
one Contact is sent in a REGISTER request, the registering UA intends
to associate all of the URIs in these Contact header field values with
the address-of-record present in the To field. This list can be
prioritized with the "q" parameter in the Contact header field. The "q"
parameter indicates a relative preference for the particular Contact
header field value compared to other bindings for this address-of-record.
A value of -1 indicates the qValue paramater
is not set.
Parameters:
qValue - - the new float value of the q-value parameter.
throws:
InvalidArgumentException - if the q-value parameter value is not-1 or between 0 and 1. |
| setWildCard | | public void setWildCard()(Code) | | Sets a wildcard on this contact address that is "*" is assigned to the
contact header so that the header will have the format of Contact: *.
since:
v1.2 |
|
|