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 */ 26 package gov.nist.javax.sip.header.extensions; 27 28 29 30 import java.text.ParseException; 31 32 import javax.sip.header.Header; 33 import 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 */ 139 public 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 */ setToTag(String tag)160 public void setToTag(String tag) throws ParseException; setFromTag(String tag)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 getToTag()179 public String getToTag(); getFromTag()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 setCallId(String callId)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 getCallId()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