001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.io.IOException;
030:
031: /**
032: * This interface defines a datagram connection which knows
033: * it's local end point address.
034: * The protocol is transaction oriented, and delivery and duplicate
035: * protection are not guaranteed. Applications requiring ordered
036: * reliable delivery of streams of data should use
037: * the <code>SocketConnection</code>.
038: * <p>
039: * A <code>UDPDatagramConnection</code> is returned from
040: * <code>Connector.open()</code> in response to a request to
041: * open a <code>datagram://</code> URL connection string.
042: * If the connection string omits both the <code>host</code>
043: * and <code>port</code> fields in the URL string, then the
044: * system will allocate an available port. The local
045: * address and the local port can be discovered using
046: * the accessor methods within this interface.
047: * </p>
048: * <p>
049: * The syntax described here for the datagram URL connection string
050: * is also valid for the <code>Datagram.setAddress()</code> method
051: * used to assign a destination address to a <code>Datagram</code>
052: * to be sent. e.g., <code>datagram://</code><em>host:port</em>
053: * </p>
054: * <H2>
055: * BNF Format for Connector.open() string
056: * </H2>
057: * <P>
058: * The URI must conform to the BNF syntax specified below. If the URI
059: * does not conform to this syntax, an <code>IllegalArgumentException</code>
060: * is thrown.
061: * </P>
062: * <TABLE BORDER="1">
063: * <TR>
064: * <TD><datagram_connection_string> </TD>
065: * <TD>::= "<strong>datagram://</strong>" |
066: * "<strong>datagram://</strong>"<hostport> </TD>
067: * </TR>
068: * <TR>
069: * <TD><hostport> </TD>
070: * <TD>::= <I>host</I> ":" <I>port </I> </TD>
071: * </TR>
072: * <TR>
073: * <TD><host> </TD>
074: * <TD>::= <I>host name or IP address </I>
075: * (omitted for inbound connections) </TD>
076: * </TR>
077: * <TR>
078: * <TD><port> </TD>
079: * <TD>::= <I>numeric port number </I>(omitted for system assigned port) </TD>
080: * </TR>
081: * </TABLE>
082: */
083:
084: public interface UDPDatagramConnection extends DatagramConnection {
085:
086: /**
087: * Gets the local address to which the
088: * datagram connection is bound.
089: *
090: * <P>The host address(IP number) that can be used to connect to this
091: * end of the datagram connection from an external system.
092: * Since IP addresses may be dynamically assigned, a remote application
093: * will need to be robust in the face of IP number reassignment.</P>
094: * <P> The local hostname (if available) can be accessed from
095: * <code> System.getProperty("microedition.hostname")</code>
096: * </P>
097: *
098: * @return the local address to which the datagram connection is bound.
099: * @exception IOException if the connection was closed.
100: * @see ServerSocketConnection
101: */
102: public String getLocalAddress() throws IOException;
103:
104: /**
105: * Returns the local port to which this datagram connection is bound.
106: *
107: * @return the local port number to which this datagram connection
108: * is connected.
109: * @exception IOException if the connection was closed.
110: * @see ServerSocketConnection
111: */
112: public int getLocalPort() throws IOException;
113: }
|