1/*
2 * Conditions Of Use
3 *
4 * This software was developed by employees of the National Institute of
5 * Standards and Technology (NIST), an agency of the Federal Government.
6 * Pursuant to title 15 Untied States Code Section 105, works of NIST
7 * employees are not subject to copyright protection in the United States
8 * and are considered to be in the public domain.  As a result, a formal
9 * license is not needed to use the software.
10 *
11 * This software is provided by NIST as a service and is expressly
12 * provided "AS IS."  NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED
13 * OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF
14 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT
15 * AND DATA ACCURACY.  NIST does not warrant or make any representations
16 * regarding the use of the software or the results thereof, including but
17 * not limited to the correctness, accuracy, reliability or usefulness of
18 * the software.
19 *
20 * Permission to use this software is contingent upon your acceptance
21 * of the terms of this agreement
22 *
23 * .
24 *
25 */
26package gov.nist.javax.sip.header.extensions;
27
28
29
30import java.text.ParseException;
31
32import javax.sip.header.Header;
33import javax.sip.header.Parameters;
34
35
36
37/**
38 * The From header field indicates the logical identity of the initiator
39
40 * of the request, possibly the user's address-of-record. This may be different
41
42 * from the initiator of the dialog.  Requests sent by the callee to the caller
43
44 * use the callee's address in the From header field.
45
46 * <p>
47
48 * Like the To header field, it contains a URI and optionally a display name,
49
50 * encapsulated in a {@link javax.sip.address.Address}.  It is used by SIP
51
52 * elements to determine which processing rules to apply to a request (for
53
54 * example, automatic call rejection). As such, it is very important that the
55
56 * From URI not contain IP addresses or the FQDN of the host on which the UA is
57
58 * running, since these are not logical names.
59
60 * <p>
61
62 * The From header field allows for a display name.  A UAC SHOULD use
63
64 * the display name "Anonymous", along with a syntactically correct, but
65
66 * otherwise meaningless URI (like sip:thisis@anonymous.invalid), if the
67
68 * identity of the client is to remain hidden.
69
70 * <p>
71
72 * Usually, the value that populates the From header field in requests
73
74 * generated by a particular UA is pre-provisioned by the user or by the
75
76 * administrators of the user's local domain.  If a particular UA is used by
77
78 * multiple users, it might have switchable profiles that include a URI
79
80 * corresponding to the identity of the profiled user. Recipients of requests
81
82 * can authenticate the originator of a request in order to ascertain that
83
84 * they are who their From header field claims they are.
85
86 * <p>
87
88 * Two From header fields are equivalent if their URIs match, and their
89
90 * parameters match. Extension parameters in one header field, not present in
91
92 * the other are ignored for the purposes of comparison. This means that the
93
94 * display name and presence or absence of angle brackets do not affect
95
96 * matching.
97
98 * <ul>
99
100 * <li> The "Tag" parameter - is used in the To and From header fields of SIP
101
102 * messages.  It serves as a general mechanism to identify a dialog, which is
103
104 * the combination of the Call-ID along with two tags, one from each
105
106 * participant in the dialog.  When a User Agent sends a request outside of a dialog,
107
108 * it contains a From tag only, providing "half" of the dialog ID. The dialog
109
110 * is completed from the response(s), each of which contributes the second half
111
112 * in the To header field. When a tag is generated by a User Agent for insertion into
113
114 * a request or response, it MUST be globally unique and cryptographically
115
116 * random with at least 32 bits of randomness. Besides the requirement for
117
118 * global uniqueness, the algorithm for generating a tag is implementation
119
120 * specific.  Tags are helpful in fault tolerant systems, where a dialog is to
121
122 * be recovered on an alternate server after a failure.  A UAS can select the
123
124 * tag in such a way that a backup can recognize a request as part of a dialog
125
126 * on the failed server, and therefore determine that it should attempt to
127
128 * recover the dialog and any other state associated with it.
129
130 * </ul>
131 * For Example:<br>
132 * <code>From: "Bob" sips:bob@biloxi.com ;tag=a48s<br>
133 * From: sip:+12125551212@phone2net.com;tag=887s<br>
134 * From: Anonymous sip:c8oqz84zk7z@privacy.org;tag=hyh8</code>
135 *
136 * @version 1.1
137 * @author jean.deruelle@gmail.com
138 */
139public interface JoinHeader extends Parameters, Header {
140
141
142
143    /**
144
145     * Sets the tag parameter of the FromHeader. The tag in the From field of a
146     * request identifies the peer of the dialog. When a UA sends a request
147     * outside of a dialog, it contains a From tag only, providing "half" of
148     * the dialog Identifier.
149     * <p>
150     * The From Header MUST contain a new "tag" parameter, chosen by the UAC
151     * applicaton. Once the initial From "tag" is assigned it should not be
152     * manipulated by the application. That is on the client side for outbound
153     * requests the application is responsible for Tag assigmennment, after
154     * dialog establishment the stack will take care of Tag assignment.
155     *
156     * @param tag - the new tag of the FromHeader
157     * @throws ParseException which signals that an error has been reached
158     * unexpectedly while parsing the Tag value.
159     */
160    public void setToTag(String tag) throws ParseException;
161    public void setFromTag(String tag) throws ParseException;
162
163
164
165
166
167    /**
168
169     * Gets the tag of FromHeader. The Tag parameter identified the Peer of the
170
171     * dialogue and must always be present.
172
173     *
174
175     * @return the tag parameter of the FromHeader.
176
177     */
178
179    public String getToTag();
180    public String getFromTag();
181
182
183    /**
184
185     * Sets the Call-Id of the CallIdHeader. The CallId parameter uniquely
186
187     * identifies a serious of messages within a dialogue.
188
189     *
190
191     * @param callId - the string value of the Call-Id of this CallIdHeader.
192
193     * @throws ParseException which signals that an error has been reached
194
195     * unexpectedly while parsing the callId value.
196
197     */
198
199    public void setCallId(String callId) throws ParseException;
200
201
202
203    /**
204
205     * Returns the Call-Id of CallIdHeader. The CallId parameter uniquely
206
207     * identifies a series of messages within a dialogue.
208
209     *
210
211     * @return the String value of the Call-Id of this CallIdHeader
212
213     */
214
215    public String getCallId();
216
217
218
219    /**
220
221     * Name of JoinHeader
222
223     */
224
225    public final static String NAME = "Join";
226
227}
228
229
230