001: /*
002: * Portions Copyright 2000-2007 Sun Microsystems, Inc. All Rights
003: * Reserved. Use is subject to license terms.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.sip;
027:
028: import java.io.*;
029:
030: /**
031: * SipClientConnection represents SIP client transaction.
032: * Application can create a new SipClientConnection with Connector
033: * or SipDialog object.
034: * @see JSR180 spec, v 1.0.1, p 21-33
035: *
036: */
037: public interface SipClientConnection extends SipConnection {
038:
039: /**
040: * Initializes SipClientConnection to a specific SIP
041: * request method (REGISTER, INVITE, MESSAGE, ...).
042: * @see JSR180 spec, v 1.0.1, p 25
043: *
044: * @param method - Name of the method
045: * @param scn - SipConnectionNotifier to which the request will be
046: * associated. If SipConnectionNotifier is null the request will not be
047: * associated to a user defined listening point.
048: * @throws IllegalArgumentException - if the method is invalid
049: * @throws SipException - INVALID_STATE if the request can not be set,
050: * because of wrong state in SipClientConnection. Furthermore, ACK and
051: * CANCEL methods can not be initialized in Created state.
052: */
053: public void initRequest(java.lang.String method,
054: javax.microedition.sip.SipConnectionNotifier scn)
055: throws IllegalArgumentException, SipException;
056:
057: /**
058: * Sets Request-URI explicitly. Request-URI can be set only in
059: * Initialized state.
060: * @see JSR180 spec, v 1.0.1, p 26
061: *
062: * @param URI - Request-URI
063: * @throws IllegalArgumentException - MAY be thrown if the URI is invalid
064: * @throws SipException - INVALID_STATE if the Request-URI can not be set,
065: * because of wrong state.
066: * INVALID_OPERATION if the Request-URI is not allowed to be set.
067: */
068: public void setRequestURI(java.lang.String URI)
069: throws IllegalArgumentException, SipException;
070:
071: /**
072: * Convenience method to initialize SipClientConnection with SIP request
073: * method ACK. ACK can be applied only to INVITE request.
074: * @see JSR180 spec, v 1.0.1, p 27
075: *
076: */
077: public void initAck() throws SipException;
078:
079: /**
080: * Convenience method to initialize SipClientConnection with SIP request
081: * method CANCEL.
082: * @see JSR180 spec, v 1.0.1, p 27-28
083: *
084: */
085: public javax.microedition.sip.SipClientConnection initCancel()
086: throws SipException;
087:
088: /**
089: * Receives SIP response message. The receive method will update the
090: * SipClientConnection with the last new received response.
091: * If no message is received the method will block until something is
092: * received or specified amount of time has elapsed.
093: * @see JSR180 spec, v 1.0.1, p 28
094: *
095: * @param timeout - the maximum time to wait in milliseconds.
096: * 0 = do not wait, just poll
097: * @return Returns true if response was received. Returns false if
098: * the given timeout elapsed and no response was received.
099: * @throws SipException - INVALID_STATE if the receive can not be
100: * called because of wrong state.
101: * @throws IOException - if the message could not be received or
102: * because of network failure
103: */
104: public boolean receive(long timeout) throws SipException,
105: IOException;
106:
107: /**
108: * Sets the listener for incoming responses. If a listener is
109: * already set it
110: * will be overwritten. Setting listener to null will remove the current
111: * listener.
112: * @see JSR180 spec, v 1.0.1, p 28
113: *
114: * @param sccl - reference to the listener object. Value null will remove
115: * the existing listener.
116: * @throws IOException - if the connection is closed.
117: */
118: public void setListener(
119: javax.microedition.sip.SipClientConnectionListener sccl)
120: throws IOException;
121:
122: /**
123: * Enables the refresh on for the request to be sent. The method return a
124: * refresh ID, which can be used to update or stop the refresh.
125: * @see JSR180 spec, v 1.0.1, p 29
126: *
127: * @param srl - callback interface for refresh events, if this is null the
128: * method returns 0 and refresh is not enabled.
129: * @return refresh ID. If the request is not refreshable returns 0.
130: * @throws SipException - INVALID_STATE if the refresh can not be enabled
131: * in this state.
132: */
133: public int enableRefresh(
134: javax.microedition.sip.SipRefreshListener srl)
135: throws SipException;
136:
137: /**
138: * Sets credentials for possible digest authentication.
139: * @see JSR180 spec, v 1.0.1, p 29
140: *
141: * @param username - username (for this protection domain)
142: * @param password - user password (for this protection domain)
143: * @param realm - defines the protection domain
144: * @throws SipException - INVALID_STATE if the credentials can not
145: * be set in this state.
146: * @throws NullPointerException - if the username, password or realm is null
147: */
148: public void setCredentials(java.lang.String username,
149: java.lang.String password, java.lang.String realm)
150: throws SipException;
151: }
|