com.nokia.mid.messaging
Interface MessageConnection

All Superinterfaces:

javax.microedition.io.Connection

public interface MessageConnection

extends javax.microedition.io.Connection

The MessageConnection interface defines the basic functionality for sending and receiving message.

'Client' mode connections (i.e. for only sending messages) are created by passing a string identifying a destination address to the Connector.open() method.

'Server' mode connections (i.e. for receiving and sending messages) are created by passing a string that identifies a port, or equivalent, on the local host to the Connector.open() method. If the requested port number is already reserved, either by some system application or by another MIDlet, the Connector.open() method shall throw an IOException. MIDlets shall be able to open MessageConnections for any unreserved port number, although security permissions may not allow it to send or receive messages using that port number.

The 'scheme' that identifies the used protocol is specific to the given protocol. This interface does not assume any specific protocol but is intended for all wireless messaging protocols.

Field Summary

static int	BINARY_MESSAGE Constant for a message type for binary messages (value = 2).
static int	TEXT_MESSAGE Constant for a message type for text messages (value = 1).

Method Summary

Message	newMessage(int type) Constructs a new message object of a given type.
Message	newMessage(int type, java.lang.String address) Constructs a new message object of a given type and initializes it with the given destination address.
int	numberOfMessages(Message msg) Returns how many SMS messages will be needed for sending the Message given as the parameter.
Message	receive() Receives a message If there are no Messages for this Connection waiting, this message will block until a message for this Connection is received, or the Connection is closed.
void	registerMessageListener(MessageListener l) Registers a MessageListener object.
void	send(Message msg) Sends the message

Methods inherited from interface javax.microedition.io.Connection

close

Field Detail

TEXT_MESSAGE

public static final int TEXT_MESSAGE

Constant for a message type for text messages (value = 1). Using this constant as the type parameter in the newMessage() methods shall cause the newly created Message to be an instance implementing the TextMessage interface.

See Also:

Constant Field Values

BINARY_MESSAGE

public static final int BINARY_MESSAGE

Constant for a message type for binary messages (value = 2). Using this constant as the type parameter in the newMessage() methods shall cause the newly created Message to be an instance implementing the BinaryMessage interface.

See Also:

Constant Field Values

Method Detail

newMessage

public Message newMessage(int type)

Constructs a new message object of a given type.

When this method is called from a 'client' mode connection, the newly created Message has the destination address set to the address identified when this Connection was created.

When this method is called from a 'server' mode connection, the newly created Message does not have the destination address set. It must be set by the application before trying to send the message.

Parameters:

type - the type of message to be created. There are constants for basic types defined in this interface

Returns:

Message object for a given type of message

newMessage

public Message newMessage(int type,
                          java.lang.String address)

Constructs a new message object of a given type and initializes it with the given destination address.

Parameters:

type - the type of message to be created. There are constants for basic types defined in this interface

address - destination address for the new message

Returns:

Message object for a given type of message

send

public void send(Message msg)
          throws java.io.IOException,
                 java.io.InterruptedIOException

Sends the message

Parameters:

msg - the message to be sent

Throws:

java.io.IOException - if the message could not be sent, because of a network communication failure.

java.lang.InvalidArgumentException - if the message could not be sent, because of invalid information in the Message object. This exception is also thrown if the payload of the message exceeds the maximum length for the given messaging protocol.

java.io.InterruptedIOException - if a timeout occurs while trying to send the message or if this Connection object is closed during this send operation

java.lang.SecurityException - if the application does not have a permission to send the message

receive

public Message receive()
                throws java.io.IOException,
                       java.io.InterruptedIOException

Receives a message

If there are no Messages for this Connection waiting, this message will block until a message for this Connection is received, or the Connection is closed.

Returns:

a Message object representing the information in the received message

Throws:

java.io.IOException - if an error occurs while receiving a message

java.io.InterruptedIOException - if this Connection object is closed during this receive method call

java.lang.SecurityException - if the application does not have a permission to receive messages using the given port number

registerMessageListener

public void registerMessageListener(MessageListener l)
                             throws java.io.IOException

Registers a MessageListener object.

The platform will notify this listener object when a message has been received to this MessageConnection.

If there are incoming messages in the queue of this MessageConnection that have not been retrieved by the the application prior to calling this method, the newly registered listener object will be notified immediately once for each such income message in the queue.

There can be at most one listener object registered for a MessageConnection object at any given point in time.

The currently registered listener can be de-registered by passing in null as the parameter. If null is passed and there is no currently registered listener, the call has no effect.

Parameters:

l - MessageListener object to be registered; if null, the currently registered listener object will be de-registered and will no longer receive events

Throws:

java.io.IOException - if a listener object has already been registered with this MessageConnection

java.lang.SecurityException - if the application does not have a permission to receive messages using the given port number

numberOfMessages

public int numberOfMessages(Message msg)

Returns how many SMS messages will be needed for sending the Message given as the parameter.

Note that this method does not actually send the message, it will only calculate the number of SMS messages needed for sending the message.

This method will calculate the number of messages needed when this message is split into the SMS messages using the concatenation mechanisms provided by the GSM SMS protocol. This method does not take into account possible limitations of the implementation that may limit the number of SMS messages that can be sent using this feature.

This specification guarantees only that implementations are able to send and receive messages that use up to 3 SMS protocol messages. Thus, if this method returns a value larger than 3, the application is not advised to send the message unless it has reason to believe that the recipient is able to handle the indicated number of messages

Parameters:

msg - the message to be used for the calculation

Returns:

number of SMS messages needed for sending the message. Returns 0 if the Message object can not be sent as GSM SMS at all.