jain.protocol.ip.sip.message
Class RegisterMessage

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--jain.protocol.ip.sip.message.Message
              |
              +--jain.protocol.ip.sip.message.RequestMessage
                    |
                    +--jain.protocol.ip.sip.message.RegisterMessage

public final class RegisterMessage

extends RequestMessage

This class represents a REGISTER request message. A client uses the RegisterMessage to register the address listed in the ToHeader with a SIP server.

A user agent may register with a local server on startup by sending a RegisterMessage to the well-known "all SIP servers" multicast address "sip.mcast.net" (224.0.1.75). This RegisterMessage should be scoped to ensure it is not forwarded beyond the boundaries of the administrative system. This may be done with either TTL or administrative scopes, depending on what is implemented in the network. SIP user agents may listen to that address and use it to become aware of the location of other local users; however, they do not respond to the RegisterMessage. A user agent may also be configured with the address of a registrar server to which it sends a RegisterMessage upon startup.

RegisterMessages are processed in the order received. Clients should avoid sending a new RegisterMessage (as opposed to a retransmission) until they have received the ResponseMessage from the server for the previous one.

Clients may register from different locations, by necessity using different CallIdHeaders. Thus, the CSeqHeader cannot be used to enforce ordering. Since registrations are additive, ordering is less of a problem than if each RegisterMessage completely replaced all earlier ones.

The meaning of the RegisterMessage Headers is defined as follows. We define "address-of-record" as the SIP address that the registry knows the registrand, typically of the form "user@domain" rather than "user@host". In third-party registration, the entity issuing the RegisterMessage is different from the entity being registered.

ToHeader: The ToHeader contains the address-of-record whose registration is to be created or updated.

FromHeader: The FromHeader contains the address-of-record of the person responsible for the registration. For first-party registration, it is identical to the ToHeader value.

RequestURI: The RequestURI names the destination of the RegisterMessage, i.e., the domain of the registrar. The user name must be empty. Generally, the domains in the RequestURI and the ToHeader have the same value; however, it is possible to register as a "visitor", while maintaining one's name. For example, a traveller sip:alice@acme.com (ToHeader) might register under the RequestURI sip:atlanta.hiayh.org , with the former as the ToHeader and the latter as the RequestURI. The RegisterMessaget is no longer forwarded once it has reached the server whose authoritative domain is the one listed in the RequestURI.

CallIdHeader: All RegisterMessage from a client should use the same CallIdHeader value, at least within the same reboot cycle.

CSeqHeader: RegisterMessages with the same CallIdHeader must have increasing CSeqHeader sequence numbers. However, the server does not reject out-of-order RegisterMessages.

ContactHeader: The RegisterMessage may contain ContactHeaders; future non-REGISTER RequestMessages for the URI given in the ToHeader should be directed to the address(es) given in the ContactHeader(s).

If the request does not contain a ContactHeader, the registration remains unchanged. This is useful to obtain the current list of registrations in the ResponseMessage. Registrations using SIP URIs that differ in one or more of host, port, transport or maddr from an existing registration are added to the list of registrations. Other URI types are compared according to the standard URI equivalency rules for the URI schema. If the URIs are equivalent to that of an existing registration, the new registration replaces the old one if it has a higher q value or, for the same value of q, if the ttl value is higher. All current registrations must share the same action value. Registrations that have a different action than current registrations for the same user must be rejected with status of CONFLICT.

A proxy server ignores the q parameter when processing non-REGISTER RequestMessages, while a redirect server simply returns that parameter in its ContactHeader. Having the proxy server interpret the q parameter is not sufficient to guide proxy behavior, as it is not clear, for example, how long it is supposed to wait between trying addresses.

If the registration is changed while a user agent or proxy server processes an InviteMessage, the new information should be used. This allows a service known as "directed pick-up". In the telephone network, directed pickup permits a user at a remote station who hears his own phone ringing to pick up at that station, dial an access code, and be connected to the calling user as if he had answered his own phone.

A server MAY choose any duration for the registration lifetime. Registrations not refreshed after this amount of time should be silently discarded. ResponseMessages to a RegisterMessage should include an ExpiresHeader or expires ContactHeader parameters, indicating the time at which the server will drop the registration. If none is present, one hour is assumed. Clients may request a registration lifetime by indicating the time in an ExpiresHeader in the RegisterMessage. A server should not use a higher lifetime than the one requested, but may use a lower one. A single address (if host-independent) may be registered from several different clients.

A client cancels an existing registration by sending a RegisterMessage with an expiration time of zero seconds for a particular ContactHeader or a wildcard ContactHeader. Registrations are matched based on the user, host, port and maddr parameters.

The server should return the current list of registrations in the OK response as ContactHeaders.

It is particularly important that RegisterMessages are authenticated since they allow to redirect future RequestMessages.

Beyond its use as a simple location service, this method is needed if there are several SIP servers on a single host. In that case, only one of the servers can use the default port number.

Support of this method is recommended.

Version:

0.6

See Also:

RequestMessage, ResponseMessage, InviteMessage, AckMessage, ByeMessage, FromHeader, ToHeader, CallIdHeader, CSeqHeader, ExpiresHeader, ContactHeader, Serialized Form

Field Summary

static java.lang.String

method RegisterMessage's method

Constructor Summary

RegisterMessage(java.lang.Object source, URI requestURI, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, ViaHeader[] viaHeaders, ContactHeader[] contactHeaders)
Constructor of RegisterMessage with body

RegisterMessage(java.lang.Object source, URI requestURI, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, ViaHeader[] viaHeaders, ContactHeader[] contactHeaders, java.lang.Object body, ContentTypeHeader contentTypeHeader)
Constructor of RegisterMessage with body

Methods inherited from class jain.protocol.ip.sip.message.RequestMessage

addViaHeader, getAuthorizationHeader, getHideHeader, getMaxForwardsHeader, getMethod, getProxyAuthorizationHeader, getProxyRequireHeaders, getRequestURI, getRequireHeaders, getResponseKeyHeader, getRouteHeaders, getStartLine, hasAuthorizationHeader, hasHideHeader, hasMaxForwardsHeader, hasProxyAuthorizationHeader, hasProxyRequireHeaders, hasRequireHeaders, hasResponseKeyHeader, hasRouteHeaders, removeAuthorizationHeader, removeHideHeader, removeMaxForwardsHeader, removeProxyAuthorizationHeader, removeProxyRequireHeaders, removeRequireHeaders, removeResponseKeyHeader, removeRouteHeaders, setAuthorizationHeader, setHideHeader, setMaxForwardsHeader, setProxyAuthorizationHeader, setProxyRequireHeaders, setRequestURI, setRequireHeaders, setResponseKeyHeader, setRouteHeaders

Methods inherited from class jain.protocol.ip.sip.message.Message

addHeader, addHeaders, clone, equals, getAcceptEncodingHeaders, getAcceptHeaders, getAcceptLanguageHeaders, getAllHeaders, getBody, getCallIdHeader, getContactHeaders, getContentEncodingHeaders, getContentLengthHeader, getContentTypeHeader, getCSeqHeader, getDateHeader, getEncryptionHeader, getExpiresHeader, getFromHeader, getHeader, getHeaders, getOrganizationHeader, getRecordRouteHeaders, getRetryAfterHeader, getTimestampHeader, getToHeader, getUserAgentHeaders, getVersionMajor, getVersionMinor, getViaHeaders, hasAcceptEncodingHeaders, hasAcceptHeaders, hasAcceptLanguageHeaders, hasBody, hasContactHeaders, hasContentEncodingHeaders, hasContentLengthHeader, hasContentTypeHeader, hasDateHeader, hasEncryptionHeader, hasExpiresHeader, hasHeaders, hasOrganizationHeader, hasRecordRouteHeaders, hasRetryAfterHeader, hasTimestampHeader, hasUserAgentHeaders, isRequest, removeAcceptEncodingHeaders, removeAcceptHeaders, removeAcceptLanguageHeaders, removeBody, removeContactHeaders, removeContentEncodingHeaders, removeContentLengthHeader, removeDateHeader, removeEncryptionHeader, removeExpiresHeader, removeHeader, removeHeaders, removeOrganizationHeader, removeRecordRouteHeaders, removeRetryAfterHeader, removeTimestampHeader, removeUserAgentHeaders, setAcceptEncodingHeaders, setAcceptHeaders, setAcceptLanguageHeaders, setBody, setCallIdHeader, setContactHeaders, setContentEncodingHeaders, setContentLengthHeader, setContentTypeHeader, setCSeqHeader, setDateHeader, setEncryptionHeader, setExpiresHeader, setFromHeader, setHeader, setHeaders, setOrganizationHeader, setRecordRouteHeaders, setRetryAfterHeader, setTimestampHeader, setToHeader, setUserAgentHeaders, setVersion, setViaHeaders, toString

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

method

public static final java.lang.String method

RegisterMessage's method

Constructor Detail

RegisterMessage

public RegisterMessage(java.lang.Object source,
                       URI requestURI,
                       CallIdHeader callIdHeader,
                       CSeqHeader cSeqHeader,
                       FromHeader fromHeader,
                       ToHeader toHeader,
                       ViaHeader[] viaHeaders,
                       ContactHeader[] contactHeaders)
                throws java.lang.IllegalArgumentException

Constructor of RegisterMessage with body

Parameters:

source - source of the RegisterMessage

requestURI - Request URI

callIdHeader - CallIdHeader

cSeqHeader - CSeqHeader

fromHeader - FromHeader

toHeader - ToHeader

viaHeaders - ViaHeaders

contactHeaders - ContactHeaders

Throws:

java.lang.IllegalArgumentException - if any arguments are invalid

RegisterMessage

public RegisterMessage(java.lang.Object source,
                       URI requestURI,
                       CallIdHeader callIdHeader,
                       CSeqHeader cSeqHeader,
                       FromHeader fromHeader,
                       ToHeader toHeader,
                       ViaHeader[] viaHeaders,
                       ContactHeader[] contactHeaders,
                       java.lang.Object body,
                       ContentTypeHeader contentTypeHeader)
                throws java.lang.IllegalArgumentException

Constructor of RegisterMessage with body

Parameters:

source - source of the RegisterMessage

requestURI - Request URI

callIdHeader - CallIdHeader

cSeqHeader - CSeqHeader

fromHeader - FromHeader

toHeader - ToHeader

viaHeaders - ViaHeaders

contactHeaders - ContactHeaders

body - body

contentTypeHeader - ContentTypeHeader

Throws:

java.lang.IllegalArgumentException - if any arguments are invalid