|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.io.DatagramConnectionBase
public abstract class 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 static long |
DEFAULT_TIMEOUT
|
|
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
|
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(String address)
Determines if a received datagram is destined for the connection. |
|
protected boolean |
isAddressed(DatagramAddressBase 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(String address,
boolean swap)
Builds a new datagram address base from provided string. |
|
DatagramAddressBase |
newDatagramAddressBase(DatagramAddressBase addressBase,
boolean swap)
Builds a new datagram address base cloned from provided one. |
|
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 |
---|
protected static long DEFAULT_TIMEOUT
protected DatagramAddressBase _addressBase
protected DatagramAddressBase _receiveFilter
protected DatagramTransportBase _transport
protected Datagram[] _sendingDatagrams
protected Hashtable _properties
protected int _flags
protected int _validFlags
protected long _timeout
protected boolean _isActive
protected DatagramStatusListener _listener
protected boolean _isTimeOutSet
Constructor Detail |
---|
public DatagramConnectionBase()
Method Detail |
---|
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 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.
close
in interface Connection
IOException
- If an I/O error occurs.public int getMaximumLength() throws IOException
getMaximumLength
in interface DatagramConnection
IOException
- If an I/O error occurs.public int getNominalLength() throws IOException
getNominalLength
in interface DatagramConnection
IOException
- If an I/O error occurs.public void send(Datagram datagram) throws IOException
send
in interface DatagramConnection
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 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 boolean isAddressed(String address)
address
- the address for the datagram.
protected boolean isAddressed(DatagramAddressBase address)
address
- the address for the datagram.
public void receive(Datagram datagram) throws IOException
receive
in interface DatagramConnection
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 Datagram newDatagram() throws IOException
IOException
- If an I/O error occurs.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.
newDatagram
in interface DatagramConnection
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.
newDatagram
in interface DatagramConnection
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 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
newDatagram
in interface DatagramConnection
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 length, String address) throws IOException
newDatagram
in interface DatagramConnection
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(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 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 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 void processReceivedDatagram(Datagram datagram)
datagram
- Datagram to process.public Object setProperty(String name, Object data)
setProperty
in interface IOProperties
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 Object getProperty(String name)
getProperty
in interface IOProperties
name
- Property's name.
public void setFlag(int flag, boolean value)
setFlag
in interface IOProperties
flag
- Bit mask specifying which flags to modify.value
- New value for each flag specified in the mask.public int getFlag(int flag)
getFlag
in interface IOProperties
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 boolean isFlagSet(int flag)
isFlagSet
in interface IOProperties
flag
- Bit mask of flags to check.
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).public void setDatagramStatusListener(DatagramStatusListener listener)
listener
- Status listener to register.public DatagramStatusListener getDatagramStatusListener()
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 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.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 String getLocalAddress() throws IOException
getLocalAddress
in interface UDPDatagramConnection
IOException
- if the connection was closed.ServerSocketConnection
public int getLocalPort() throws IOException
getLocalPort
in interface UDPDatagramConnection
IOException
- if the connection was closed.ServerSocketConnection
protected void checkForClosed() throws IOException
IOException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.