1package gov.nist.javax.sip;
2
3import gov.nist.core.net.AddressResolver;
4import gov.nist.javax.sip.clientauthutils.AccountManager;
5import gov.nist.javax.sip.clientauthutils.AuthenticationHelper;
6import gov.nist.javax.sip.clientauthutils.SecureAccountManager;
7import gov.nist.javax.sip.header.extensions.JoinHeader;
8import gov.nist.javax.sip.header.extensions.ReplacesHeader;
9
10import java.io.IOException;
11import java.net.InetAddress;
12import java.net.SocketAddress;
13import java.util.Collection;
14
15import javax.sip.Dialog;
16import javax.sip.SipStack;
17import javax.sip.header.HeaderFactory;
18
19/**
20 * SIP Stack extensions to be added to the next spec revision. Only these may be safely used in
21 * the interim between now and the next release. SipStackImpl implements this interface.
22 *
23 * The following new stack initialization flags are defined (not the gov.nist prefix will be
24 * dropped when the spec is updated):
25 *
26 * <ul>
27 *<li>gov.nist.javax.sip.AUTOMATIC_DIALOG_ERROR_HANDLING
28 *<li>gov.nist.javax.sip.IS_BACK_TO_BACK_USER_AGENT
29 *<li>gov.nist.javax.sip.DELIVER_TERMINATED_EVENT_FOR_NULL_DIALOG
30 *<li>gov.nist.javax.sip.MAX_FORK_TIME_SECONDS
31 * </ul>
32 * @author M. Ranganathan
33 *
34 */
35public interface SipStackExt extends SipStack {
36
37    /**
38     * Get the collection of dialogs currently in the Dialog table. This is useful for debugging
39     * purposes.
40     *
41     */
42    public Collection<Dialog> getDialogs();
43
44    /**
45     * Get the ReferedTo dialog in the Replaces header.
46     *
47     * @return Dialog object matching the Replaces header, provided it is in an appropriate state
48     *         to be replaced, <code>null</code> otherwise
49     *
50     * @since 2.0
51     */
52    public Dialog getReplacesDialog(ReplacesHeader replacesHeader);
53
54    /**
55     * Get the authentication helper.
56     *
57     *
58     * @param accountManager -- account manager (for fetching credentials).
59     * @param headerFactory -- header factory.
60     *
61     * @return - the authentication helper which can be used for generating the appropriate
62     *         headers for handling authentication challenges for user agents.
63     *
64     * @since 2.0
65     */
66    public AuthenticationHelper getAuthenticationHelper(AccountManager accountManager,
67            HeaderFactory headerFactory);
68
69    /**
70     * Get the authentication helper.
71     *
72     *
73     * @param accountManager -- account manager (for fetching credentials).
74     * @param headerFactory -- header factory.
75     *
76     * @return - the authentication helper which can be used for generating the appropriate
77     *         headers for handling authentication challenges for user agents.
78     *
79     * @since 2.0
80     */
81    public AuthenticationHelper getSecureAuthenticationHelper(SecureAccountManager accountManager,
82            HeaderFactory headerFactory);
83
84    /**
85     * Set the address resolution interface. The address resolver allows you to register custom
86     * lookup schemes ( for example DNS SRV lookup ) that are not directly supported by the JDK.
87     *
88     * @param addressResolver -- the address resolver to set.
89     *
90     * @since 2.0
91     */
92    public void setAddressResolver(AddressResolver addressResolver);
93
94    /**
95     * Get the dialog in the Join header.
96     *
97     * @return Dialog object matching the Join header, provided it is in an appropriate state to
98     *         be replaced, <code>null</code> otherwise
99     *
100     * @since 2.0
101     */
102    public Dialog getJoinDialog(JoinHeader joinHeader);
103
104    /**
105     * Set the list of cipher suites supported by the stack. A stack can have only one set of
106     * suites. These are not validated against the supported cipher suites of the java runtime, so
107     * specifying a cipher here does not guarantee that it will work.<br>
108     * The stack has a default cipher suite of:
109     * <ul>
110     * <li> TLS_RSA_WITH_AES_128_CBC_SHA </li>
111     * <li> SSL_RSA_WITH_3DES_EDE_CBC_SHA </li>
112     * <li> TLS_DH_anon_WITH_AES_128_CBC_SHA </li>
113     * <li> SSL_DH_anon_WITH_3DES_EDE_CBC_SHA </li>
114     * </ul>
115     *
116     * <b>NOTE: This function must be called before adding a TLS listener</b>
117     *
118     * @since 2.0
119     * @param newCipherSuites -- The new set of ciphers to support.
120     *
121     */
122    public void setEnabledCipherSuites(String[] newCipherSuites);
123
124    /**
125     * Creates and binds, if necessary, a TCP socket connected to the specified
126     * destination address and port and then returns its local address.
127     *
128     * @param dst the destination address that the socket would need to connect
129     *            to.
130     * @param dstPort the port number that the connection would be established
131     * with.
132     * @param localAddress the address that we would like to bind on
133     * (null for the "any" address).
134     * @param localPort the port that we'd like our socket to bind to (0 for a
135     * random port).
136     *
137     * @return the SocketAddress that this handler would use when connecting to
138     * the specified destination address and port.
139     *
140     * @throws IOException
141     */
142    public SocketAddress obtainLocalAddress(InetAddress dst, int dstPort,
143                    InetAddress localAddress, int localPort)
144        throws IOException;
145
146}
147