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 javax.microedition.io.Connection;
029: import java.io.IOException;
030: import java.io.InterruptedIOException;
031:
032: /**
033: * SipConnection is the base interface for Sip connections.
034: * @see JSR180 spec, v 1.0.1, p 11-20
035: *
036: */
037: public interface SipConnection extends Connection {
038:
039: /**
040: * Sends the SIP message. Send must also close the OutputStream
041: * if it was opened
042: * @throws IOException - if the message could not be sent or because
043: * of network failure
044: * @throws InterruptedIOException - if a timeout occurs while
045: * either trying
046: * to send the message or if this Connection object is closed
047: * during this send operation
048: * @throws SipException - INVALID_STATE if the message cannot be sent
049: * in this state. <br> INVALID_MESSAGE there was an error
050: * in message format
051: */
052: public void send() throws IOException, SipException;
053:
054: /**
055: * Sets header value in SIP message.
056: * @see JSR180 spec, v 1.0.1, p 17
057: *
058: * @param value - the header value
059: * @throws SipException - INVALID_STATE if header can not be set in
060: * this state. <br> INVALID_OPERATION if the system does not allow to set
061: * this header.
062: * @throws IllegalArgumentException - MAY be thrown if the header or
063: * value is invalid
064: */
065: public void setHeader(String name, String value)
066: throws SipException, IllegalArgumentException;
067:
068: /**
069: * Adds a header to the SIP message.
070: * @see JSR180 spec, v 1.0.1, p 17
071: *
072: * @param name - name of the header, either in full or compact form.
073: * RFC 3261 p.32
074: * @param value - the header value
075: * @throws SipException - INVALID_STATE if header can not be added in
076: * this state. <br> INVALID_OPERATION if the system does not allow to add
077: * this header.
078: * @throws IllegalArgumentException - MAY be thrown if the header or
079: * value is invalid
080: */
081: public void addHeader(String name, String value)
082: throws SipException, IllegalArgumentException;
083:
084: /**
085: * Reomves header from the SIP message.
086: * @see JSR180 spec, v 1.0.1, p 18
087: *
088: * @param name - name of the header to be removed, either int
089: * full or compact form RFC 3261 p.32.
090: * @throws SipException - INVALID_STATE if header can not be removed in
091: * this state. <br> INVALID_OPERATION if the system does not allow to remove
092: * this header.
093: */
094: public void removeHeader(String name) throws SipException;
095:
096: /**
097: * Gets the header field value(s) of specified header type
098: * @param name - name of the header, either in full or compact form.
099: * RFC 3261 p.32
100: * @return array of header field values (topmost first), or null if the
101: * current message does not have such a header or the header is for other
102: * reason not available (e.g. message not initialized).
103: */
104: public String[] getHeaders(String name);
105:
106: /**
107: * Gets the header field value of specified header type.
108: * @param name - name of the header type, either in full or compact form.
109: * RFC 3261 p.32
110: * @return topmost header field value, or null if the
111: * current message does not have such a header or the header is for other
112: * reason not available (e.g. message not initialized).
113: */
114: public String getHeader(String name);
115:
116: /**
117: * Gets the SIP method. Applicable when a message has been
118: * initialized or received.
119: * @return SIP method name REGISTER, INVITE, NOTIFY, etc. Returns null if
120: * the method is not available.
121: */
122: public java.lang.String getMethod();
123:
124: /**
125: * Gets Request-URI.
126: * @see JSR180 spec, v 1.0.1, p 19
127: *
128: * @return Request-URI of the message. Returns null if the Request-URI
129: * is not available.
130: */
131: public java.lang.String getRequestURI();
132:
133: /**
134: * Gets SIP response status code. Available when SipClientConnection is in
135: * Proceeding or Completed state or when SipServerConnection is in
136: * Initialized state.
137: * @return status code 1xx, 2xx, 3xx, 4xx, ... Returns 0 if the status code
138: * is not available.
139: */
140: public int getStatusCode();
141:
142: /**
143: * Gets SIP response reason phrase. Available when SipClientConnection is in
144: * Proceeding or Completed state or when SipServerConnection is in
145: * Initialized state.
146: * @return reason phrase. Returns null if the reason phrase is
147: * not available.
148: */
149: public java.lang.String getReasonPhrase();
150:
151: /**
152: * Returns the current SIP dialog. This is available when the SipConnection
153: * belongs to a created SipDialog and the system has received (or sent)
154: * provisional (101-199) or final response (200).
155: * @return SipDialog object if this connection belongs to a dialog,
156: * otherwise returns null.
157: */
158: public javax.microedition.sip.SipDialog getDialog();
159:
160: /**
161: * Returns InputStream to read SIP message body content.
162: * @return InputStream to read body content
163: * @throws java.io.IOException - if the InputStream can not be opened,
164: * because of an I/O error occurred.
165: * @throws SipException - INVALID_STATE the InputStream can not be opened
166: * in this state (e.g. no message received).
167: */
168: public java.io.InputStream openContentInputStream()
169: throws IOException, SipException;
170:
171: /**
172: * Returns OutputStream to fill the SIP message body content.
173: * @see JSR180 spec, v 1.0.1, p 20
174: *
175: * @return OutputStream to write body content
176: * @throws IOException if the OutputStream can not be opened,
177: * because of an I/O error occurred.
178: * @throws SipException INVALID_STATE the OutputStream can not be opened
179: * in this state (e.g. no message initialized).
180: * UNKNOWN_LENGTH Content-Length header not set.
181: * UNKNOWN_TYPE Content-Type header not set.
182: */
183: public java.io.OutputStream openContentOutputStream()
184: throws IOException, SipException;
185: }
|