|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--net.rim.device.api.io.DatagramConnectionBase
Contains methods that handle BlackBerry Datagram connection and transmission operations.
The parameter string takes the following form:
{protocol}://[{host}]:[{port}]
A datagram connection can be opened in a "client" mode or "server" mode. If the "//{host}" part is missing then the connection is opened as a "server" (by "server", we mean that a client application initiates communication). When the "//{host}" part is specified, the connection is opened as a "client".
The following examples describe how to create UDP connections on a BlackBerry.
A datagram connection for accepting datagrams udp://:1234
A datagram connection for sending to a server: udp://123.456.789.12:1234
| Field Summary | ||
protected DatagramAddressBase |
_addressBase
|
|
protected int |
_flags
|
|
protected boolean |
_isActive
|
|
protected boolean |
_isTimeOutSet
|
|
protected DatagramStatusListener |
_listener
|
|
protected Hashtable |
_properties
|
|
protected DatagramAddressBase |
_receiveFilter
|
|
protected Datagram[] |
_sendingDatagrams
|
|
protected long |
_timeout
|
|
protected DatagramTransportBase |
_transport
|
|
protected int |
_validFlags
|
|
protected static long |
DEFAULT_TIMEOUT
|
|
| Fields inherited from interface net.rim.device.api.io.IOProperties |
CDMA_SET_FAST_DORMANCY_FLAG, FLAG_INVALID, FLAG_SET, FLAG_UNSET, GME_ADD_SRC_FIELD_FLAG, GME_DELAYED_ACK_FLAG, GME_FAIL_ON_MISSING_ROUTING_INFO_FLAG, GME_REQUEST_CONFIRMATION_FLAG, MDP_DATAGRAM_ACK_FLAG, MDP_DONT_SET_FAST_DORMANCY_FLAG, MDP_PACKET_ACK_FLAG, MOBITEX_MAILBOX_FLAG, MOBITEX_REQUEST_ACK_FLAG, UDP_RETRY_ON_NO_CONTEXT |
| Constructor Summary | ||
DatagramConnectionBase()
Creates a new DatagramConnectionBase instance. |
||
| Method Summary | ||
int |
allocateDatagramId(Datagram datagram)
Allocates an ID for the provided datagram. |
|
void |
cancel(Datagram datagram)
Attempts to cancel a sent datagram. |
|
protected void |
checkForClosed()
Determines if the connection has been closed. |
|
void |
close()
Closes the connection. |
|
void |
copyFlagsInto(DatagramBase dg)
Copies flags from the connection to the datagram. |
|
DatagramStatusListener |
getDatagramStatusListener()
Retrieves the status listener for this connection. |
|
int |
getFlag(int flag)
Retrieves state of specified flags for this connection. |
|
String |
getLocalAddress()
Retrieves local address. |
|
int |
getLocalPort()
Retrieves local port. |
|
int |
getMaximumLength()
Retrieves a datagram's maximum length. |
|
int |
getNominalLength()
Retrieves a datagram's nominal length. |
|
Object |
getProperty(String name)
Retrieves a property associated with the connection. |
|
void |
handleDatagramStatus(int datagramId,
int event,
Object context)
Handles a status change event for a datagram. |
|
protected boolean |
isAddressed(DatagramAddressBase address)
Determines if a received datagram is destined for the connection. |
|
protected boolean |
isAddressed(String address)
Determines if a received datagram is destined for the connection. |
|
boolean |
isFlagSet(int flag)
Determines if any of specified flags are set. |
|
Datagram |
newDatagram()
Builds a new datagram object with an empty 0 byte buffer. |
|
Datagram |
newDatagram(byte[] buffer)
Builds a new datagram object. |
|
Datagram |
newDatagram(byte[] buffer,
int length)
Builds a new datagram object. |
|
Datagram |
newDatagram(byte[] buffer,
int offset,
int length)
Builds a new datagram object. |
|
Datagram |
newDatagram(byte[] buffer,
int offset,
int length,
String address)
Builds a new datagram object. |
|
Datagram |
newDatagram(byte[] buffer,
int length,
String address)
Builds a new datagram object. |
|
Datagram |
newDatagram(int length)
Builds a new datagram object automatically allocating a buffer. |
|
Datagram |
newDatagram(int length,
String address)
Builds a new datagram object. |
|
DatagramAddressBase |
newDatagramAddressBase(DatagramAddressBase addressBase,
boolean swap)
Builds a new datagram address base cloned from provided one. |
|
DatagramAddressBase |
newDatagramAddressBase(String address,
boolean swap)
Builds a new datagram address base from provided string. |
|
Connection |
openPrim(String name,
int mode,
boolean timeouts)
Opens primary connection. |
|
void |
processReceivedDatagram(Datagram datagram)
Processes received datagram. |
|
void |
receive(Datagram datagram)
Receives a datagram. |
|
void |
send(Datagram datagram)
Sends a datagram. |
|
void |
setDatagramStatusListener(DatagramStatusListener listener)
Registers a status listener for this connection. |
|
void |
setFlag(int flag,
boolean value)
Sets state of specified flags for this connection. |
|
Object |
setProperty(String name,
Object data)
Associates a property with the connection. |
|
void |
setTimeout(long timeout)
Sets the timeout value for this connection. |
|
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
| Constructor Detail |
public DatagramConnectionBase()
| Method Detail |
public int allocateDatagramId(Datagram datagram)
You may need to invoke this method just before the sending the
datagram as the ID may depend on the contents of the datagram. Check the
implementation of the
getNextDatagramId
method in the underlying Transport object for more information.
If this method returns DatagramBase.DG_NULL_ID then the
datagram has no ID and the underlying connection does not
support listeners.
datagram - Datagram to receive ID.public void cancel(Datagram datagram) throws IOException
Note: This method cannot guarantee to cancel your provided datagram; at some point in the sending process, the datagram becomes uncancellable.
datagram - Datagram to cancel.IOException - If an I/O error occurs.
protected void checkForClosed()
throws IOException
public void close()
throws IOException
When the connection has been closed the behaviour of all methods except this one is undefined. Closing an already closed connection has no effect. Streams derived from a connection may remain open after this method is called. This may cause the connection to remain open (but access to its methods are rejected) until any derived streams are closed themselves.
IOException - If an I/O error occurs.public void copyFlagsInto(DatagramBase dg)
Any valid flags in the connection are copied into the given datagram, as long as the flag is not already set in the datagram. This allows setting a default value for a flag in a connection that can be overriden by the datagram.
dg - Datagram base to receive the copied flags.public DatagramStatusListener getDatagramStatusListener()
public int getFlag(int flag)
flag - Bit mask of flags to query.IOProperties.FLAG_INVALID if none of the flags specified in the mask exist,
or IOProperties.FLAG_SET if any of the flags are set, or IOProperties.FLAG_UNSET if none of the flags are set.public String getLocalAddress() throws IOException
public int getLocalPort()
throws IOException
public int getMaximumLength()
throws IOException
public int getNominalLength()
throws IOException
public Object getProperty(String name)
name - Property's name.
public void handleDatagramStatus(int datagramId,
int event,
Object context)
datagramId - Datagram ID.event - Event code for the status change event.context - Any context associated with the status event.protected boolean isAddressed(DatagramAddressBase address)
address - the address for the datagram.protected boolean isAddressed(String address)
address - the address for the datagram.public boolean isFlagSet(int flag)
flag - Bit mask of flags to check.public Datagram newDatagram() throws IOException
IOException - If an I/O error occurs.public Datagram newDatagram(byte[] buffer) throws IOException
buffer - Buffer to use for the datagram.IOException - If an I/O error occurs.public Datagram newDatagram(byte[] buffer, int length) throws IOException
buffer - Buffer to use for the datagram.length - Length of the buffer to allocate for the datagram (should
not be larger than the actual length of the buffer passed in).IOException - If an I/O error occurs.IllegalArgumentException - If the length is negative.public Datagram newDatagram(byte[] buffer, int offset, int length) throws IOException
buffer - Buffer to use for the datagram.offset - Offset into the buffer the datagram should start at.length - Length of the buffer to allocate for the datagram (should
not be larger than the actual length of the buffer passed in).IOException - If an I/O error occurs.IllegalArgumentException - If the length or offset is negative.public Datagram newDatagram(byte[] buffer, int offset, int length, String address) throws IOException
buffer - Buffer to use for the datagram.offset - Offset into the buffer the datagram should start at.length - Length of the buffer to allocate for the datagram (should
not be larger than the actual length of the buffer passed in).address - Address to which the datagram must go.IOException - If an I/O error occurs.IllegalArgumentException - If the length or offset is negative.public Datagram newDatagram(byte[] buffer, int length, String address) throws IOException
buffer - Buffer to use for the datagram.length - Length of the buffer to allocate for the datagram (should
not be larger than the actual length of the buffer passed in).address - Address to which the datagram must go.IOException - If an I/O error occurs.IllegalArgumentException - If the length or offset is negative.public Datagram newDatagram(int length) throws IOException
Note: Although the underlying buffer in the returned datagram will have enough space to contain elements equal to your provided length, its starting length will be zero becuase it's emtpy when created.
length - Length of the buffer to allocate for the datagram.IOException - If an I/O error occurs.IllegalArgumentException - If the length is negative.public Datagram newDatagram(int length, String address) throws IOException
Note: Although the underlying buffer in the returned datagram will have enough space to contain elements equal to your provided length, its starting length will be zero becuase it's emtpy when created.
length - Length of the buffer to be allocated for the datagram.address - Address to which the datagram must go.IOException - If an I/O error occurs.IllegalArgumentException - If the length is negative.public DatagramAddressBase newDatagramAddressBase(DatagramAddressBase addressBase, boolean swap)
addressBase - Address base to clone.swap - If true, swap source information for destination information
in returned address base; otherwise, produce exact clone.public DatagramAddressBase newDatagramAddressBase(String address, boolean swap)
address - String to form new address base..swap - If true, swap source information for destination information
in returned addres base; otherwise, produce exact clone.public Connection openPrim(String name, int mode, boolean timeouts) throws IOException
Note: This method is overriden in some subclasses to create protocol-specific Connection classes.
name - Address base name.mode - Modetimeouts - Use timeouts for this connection.IOException - If unable to find underlying transport class.public void processReceivedDatagram(Datagram datagram)
datagram - Datagram to process.public void receive(Datagram datagram) throws IOException
datagram - Datagram object to contain the contents of a received
datagram.IOException - If an I/O error occurs.InterruptedIOException - Timeout or upon closing the connection
with outstanding I/O.public void send(Datagram datagram) throws IOException
datagram - Datagram to send.IOException - If an I/O error occurs.IOCancelledException - If the datagram was cancelled.IOFormatException - Bad length or address.InterruptedIOException - Timeout or upon closing the connection
with outstanding I/O.public void setDatagramStatusListener(DatagramStatusListener listener)
listener - Status listener to register.
public void setFlag(int flag,
boolean value)
flag - Bit mask specifying which flags to modify.value - New value for each flag specified in the mask.public Object setProperty(String name, Object data)
name - Name for the property.data - Data for the named property; if the named property already
exists, and you provide null for this parameter, the property gets
removed.public void setTimeout(long timeout)
Note: This only has an effect if the connection was created with timeouts turned on.
timeout - New timeout value in milliseconds (specifying a value of
0 effectively turns off timeouts).
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.