001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : FromHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.header;
022:
023: import java.text.ParseException;
024:
025: /**
026: * The From header field indicates the logical identity of the initiator
027:
028: * of the request, possibly the user's address-of-record. This may be different
029:
030: * from the initiator of the dialog. Requests sent by the callee to the caller
031:
032: * use the callee's address in the From header field.
033:
034: * <p>
035:
036: * Like the To header field, it contains a URI and optionally a display name,
037:
038: * encapsulated in a {@link javax.sip.address.Address}. It is used by SIP
039:
040: * elements to determine which processing rules to apply to a request (for
041:
042: * example, automatic call rejection). As such, it is very important that the
043:
044: * From URI not contain IP addresses or the FQDN of the host on which the UA is
045:
046: * running, since these are not logical names.
047:
048: * <p>
049:
050: * The From header field allows for a display name. A UAC SHOULD use
051:
052: * the display name "Anonymous", along with a syntactically correct, but
053:
054: * otherwise meaningless URI (like sip:thisis@anonymous.invalid), if the
055:
056: * identity of the client is to remain hidden.
057:
058: * <p>
059:
060: * Usually, the value that populates the From header field in requests
061:
062: * generated by a particular UA is pre-provisioned by the user or by the
063:
064: * administrators of the user's local domain. If a particular UA is used by
065:
066: * multiple users, it might have switchable profiles that include a URI
067:
068: * corresponding to the identity of the profiled user. Recipients of requests
069:
070: * can authenticate the originator of a request in order to ascertain that
071:
072: * they are who their From header field claims they are.
073:
074: * <p>
075:
076: * Two From header fields are equivalent if their URIs match, and their
077:
078: * parameters match. Extension parameters in one header field, not present in
079:
080: * the other are ignored for the purposes of comparison. This means that the
081:
082: * display name and presence or absence of angle brackets do not affect
083:
084: * matching.
085:
086: * <ul>
087:
088: * <li> The "Tag" parameter - is used in the To and From header fields of SIP
089:
090: * messages. It serves as a general mechanism to identify a dialog, which is
091:
092: * the combination of the Call-ID along with two tags, one from each
093:
094: * participant in the dialog. When a User Agent sends a request outside of a dialog,
095:
096: * it contains a From tag only, providing "half" of the dialog ID. The dialog
097:
098: * is completed from the response(s), each of which contributes the second half
099:
100: * in the To header field. When a tag is generated by a User Agent for insertion into
101:
102: * a request or response, it MUST be globally unique and cryptographically
103:
104: * random with at least 32 bits of randomness. Besides the requirement for
105:
106: * global uniqueness, the algorithm for generating a tag is implementation
107:
108: * specific. Tags are helpful in fault tolerant systems, where a dialog is to
109:
110: * be recovered on an alternate server after a failure. A UAS can select the
111:
112: * tag in such a way that a backup can recognize a request as part of a dialog
113:
114: * on the failed server, and therefore determine that it should attempt to
115:
116: * recover the dialog and any other state associated with it.
117:
118: * </ul>
119: * For Example:<br>
120: * <code>From: "Bob" sips:bob@biloxi.com ;tag=a48s<br>
121: * From: sip:+12125551212@phone2net.com;tag=887s<br>
122: * From: Anonymous sip:c8oqz84zk7z@privacy.org;tag=hyh8</code>
123: *
124: * @author BEA Systems, NIST
125: * @version 1.2
126: */
127: public interface FromHeader extends HeaderAddress, Parameters, Header {
128:
129: /**
130:
131: * Sets the tag parameter of the FromHeader. The tag in the From field of a
132: * request identifies the peer of the dialog. When a UA sends a request
133: * outside of a dialog, it contains a From tag only, providing "half" of
134: * the dialog Identifier.
135: * <p>
136: * The From Header MUST contain a new "tag" parameter, chosen by the UAC
137: * applicaton. Once the initial From "tag" is assigned it should not be
138: * manipulated by the application. That is on the client side for outbound
139: * requests the application is responsible for Tag assigmennment, after
140: * dialog establishment the stack will take care of Tag assignment.
141: *
142: * @param tag - the new tag of the FromHeader
143: * @throws ParseException which signals that an error has been reached
144: * unexpectedly while parsing the Tag value.
145: */
146: public void setTag(String tag) throws ParseException;
147:
148: /**
149: * Gets the tag of FromHeader. The Tag parameter identified the Peer of the
150: * dialogue and must always be present.
151: *
152: * @return the tag parameter of the FromHeader.
153: */
154: public String getTag();
155:
156: /**
157: * Compare this FromHeader for equality with another. This method
158: * overrides the equals method in javax.sip.Header. This method specifies
159: * object equality as outlined by
160: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
161: * Two From header fields are equivalent if their URIs match, and their
162: * parameters match. Extension parameters in one header field, not present
163: * in the other are ignored for the purposes of comparison. This means that
164: * the display name and presence or absence of angle brackets do not affect
165: * matching. When comparing header fields, field names are always
166: * case-insensitive. Unless otherwise stated in the definition of a
167: * particular header field, field values, parameter names, and parameter
168: * values are case-insensitive. Tokens are always case-insensitive. Unless
169: * specified otherwise, values expressed as quoted strings are case-sensitive.
170: *
171: * @param obj the object to compare this FromHeader with.
172: * @return <code>true</code> if <code>obj</code> is an instance of this class
173: * representing the same FromHeader as this, <code>false</code> otherwise.
174: * @since v1.2
175: */
176: public boolean equals(Object obj);
177:
178: /**
179:
180: * Name of FromHeader
181:
182: */
183:
184: public final static String NAME = "From";
185:
186: }
|