com.siemens.icm.io
Class ATCommand

java.lang.Object
  com.siemens.icm.io.ATCommand

public class ATCommand

extends Object

The ATCommand class supports the execution of AT commands on the same way, as it would be done through a serial interface. It provides a simple manner to send strings directly to the AT-Interpreters of the device.

Because the device might provide more than one AT-Interpreter at the same time, instances of this class can be connected to the several AT-Channels of the device. Because the instances of this ATCommand class are connected directly to the different AT parsers inside the module, there are only exactly as much instances possible as the number of provided AT interpreters. Trying to cre-ate more instances of this class will cause the constructor to fail.

Because the different AT-Channels of the device might have different capabilities, these capabili-ties can be queried (Fax, Data-Transfers). It might be possible (or better be probable) that there is e.g. only one instance with CSD capabilities available.

Additionally, a callback class for unsolicited AT-Events (URCs) can be registered.

Please be aware that corresponding to the setting made by the "AT+CSCS" command the string parameters of several AT commands has to be passed in the GSM or UCS2 character set and the responses might contain strings in that character set as well. The ATCommand class does no string conversion at all which means that all converting between Java strings and GSM respectively UCS2 strings has to be done by the application itself in both directions. For easy conversion be-tween the different character sets the class ATStringConversion can be used.

To be able to deal with data connections created by this class e.g. by using the ATD command there are member variables for input and output streaming from and to data connections which are accessible via the getDataOutputStream() and getDataInputStream() functions. If the module is in transparent data mode (a data connection is active) the call of the send functions is forbidden and will cause an IllegalStateException.

For performance reasons there is no synchronization done in this class. If an instance of this class has to be accessed from different threads, it has to be ensured that the send() functions, the re-lease() function, the cancelCommand() function and the breakConnection() function are synchro-nized in the user implementation. There is only a minimal synchronisation, which prohibits sending or reading data when another thread has an ongoing data transfer. Trying to break the connection of another thread is as well not possible. An IOException will be thrown.

Currently the maximal possible length of AT commands passed via the send() methods is 815 characters, including the line feed.

See Also:

ATCommandListener, ATCommandResponseListener, ATStringConverter

Constructor Summary

ATCommand(boolean csdSupport)
Creates a new instance of the ATCommand class.

ATCommand(boolean csdSupport, boolean atEvents, boolean ring, boolean dcd, boolean dsr, boolean conn)
Creates a new instance of the ATCommand class starting only the required listeners.

Method Summary

void	addListener(ATCommandListener listener) Registers listeners to receive unsolicited AT-Events (URCs).
String	breakConnection() This function switches the module, when in CSD data call, back from transparent data mode to AT command mode.
void	cancelCommand() Cancel a running AT command.
boolean	csdSupported() Get information if the connected AT-Interpreter is able to handle CSD connections.
boolean	getCONN() Get the state of a data connection of the devices AT channel.
InputStream	getDataInputStream() This function returns the input stream for data connections.
OutputStream	getDataOutputStream() This function returns the output stream for data connections.
boolean	getDCD() Get the state of the DCD (Data Carrier Detect) signal of the devices AT channel.
boolean	getDSR() Get the state of the DSR (Data Set Ready) signal of the devices AT channel.
boolean	getRING() Get the state of the RING signal of the devices AT channel.
void	release() Release resources locked by the ATCommand class.
void	removeListener(ATCommandListener listener) Removes a listener object which has been previously added from the internal list table of listener objects.
String	send(String ATCmd) Send an AT command to the device.
void	send(String ATCmd, ATCommandResponseListener response) Send an AT command to the device.
void	setDTR(boolean SignalState) Set the state of the DTR (Data Terminal Ready) signal of the devices AT channel.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ATCommand

public ATCommand(boolean csdSupport)
          throws ATCommandFailedException,
                 IllegalStateException

Creates a new instance of the ATCommand class.
If there are no more instances possible or if it is not possible to provide possibly requested CSD support the constructor will fail with an exception.
The new ATCommand instance starts five listener threads. These listeners monitor unsolicited AT-Events, changes of serial interface signals (RING, DCD and DSR) and changes of a data connection (CONN). Each started listener thread uses 5 kbytes of RAM. If all the five listeners are not needed, another constructor is available to create an ATCommand instance which only starts the required listener threads.
Please note that the instance of the ATCommand class is opened in the state it was possibly released before. If it was released while it e.g. was waiting for the text of a SMS to be sent it might still be waiting for this SMS text after creation of a new instance.

Parameters:

csdSupport - A flag indicating if the instance of this class should have CSD support or not. It might be possible that there is an instance with CSD support created, even if it wasn't requested if there are only instances with CSD support available. But it can never happen that there is CSD support requested and an instance without created. If CSD support is requested and there is no instance with CSD available an IllegalStateException will be thrown.

Throws:

IllegalStateException - if there isn't any instance of the AT interpreter with the requested capabilities available.

ATCommandFailedException - if the connection to the AT-Interpreter fails because of some internal reasons (e.g. because the virtual COM port cannot be opened in the PC emulator).

See Also:

ATCommandListener

ATCommand

public ATCommand(boolean csdSupport,
                 boolean atEvents,
                 boolean ring,
                 boolean dcd,
                 boolean dsr,
                 boolean conn)
          throws ATCommandFailedException,
                 IllegalStateException

Creates a new instance of the ATCommand class starting only the required listeners.
If there are no more instances possible or if it is not possible to provide possibly requested CSD support the constructor will fail with an exception.
The available listeners monitor unsolicited AT-Events, changes of serial interface signals (RING, DCD and DSR) and changes of a data connection (CONN). Each started listener thread uses 5 kbytes of RAM.
Please note that the instance of the ATCommand class is opened in the state it was possibly released before. If it was released while it e.g. was waiting for the text of a SMS to be sent it might still be waiting for this SMS text after creation of a new instance.

Parameters:

csdSupport - A flag indicating if the instance of this class should have CSD support or not. It might be possible that there is an instance with CSD support created, even if it wasn't requested if there are only instances with CSD support available. But it can never happen that there is CSD support requested and an instance without created. If CSD support is requested and there is no instance with CSD available an IllegalStateException will be thrown.

atEvents - listener for unsolicited AT-Events (URCs)

ring - listener for changes of the serial interface signal RING

dcd - listener for changes of the serial interface signal DCD (Data Carrier Detect)

dsr - listener for changes of the serial interface signal DSR (Data Set Ready)

conn - listener for changes of the state of a data connection

Throws:

IllegalStateException - if there isn't any instance of the AT interpreter with the requested capabilities available.

ATCommandFailedException - if the connection to the AT-Interpreter fails because of some internal reasons (e.g. because the virtual COM port cannot be opened in the PC emulator).

See Also:

ATCommandListener

Method Detail

release

public void release()
             throws ATCommandFailedException

Release resources locked by the ATCommand class. After calling this function the class instance cannot be used any more but the resources are free to be used by a new instance.
Please note that the current state of the instance of the ATCommand class is not changed by releasing it. If it is e.g. waiting for the text of a SMS to be sent when it is released it might still be waiting for this SMS text after creation of a new instance.

Throws:

ATCommandFailedException - if releasing locked resources fails because of:

illegal instance state (e.g. released)

some internal reasons

send

public String send(String ATCmd)
            throws ATCommandFailedException,
                   IllegalStateException,
                   IllegalArgumentException

Send an AT command to the device. There will be no interpretation of the command which means that the string to send should contain a valid command which will be understood by the module including the finalizing line feed "\r" or the corresponding line end character set in the S3 register! The function will be a blocking call which means that the calling thread will be interrupted until the module returns a response.

Currently there are 1024 bytes reserved to temporary store the response internal inside the virtual machine. Some AT commands return responses which might be longer (e.g. reading a phone book or the provider list at once). In this case an ATCommandFailedException will be thrown. To avoid this an application should use the possible problematic commands in their format returning only single entries.

Attention:
If there are strings sent to the AT command interpreter by this method which are not valid AT commands because they don't start with "AT" they will be ignored by the AT command interpreter, no response will be sent and this method is blocking infinitely! The application should protect itself of sending wrong AT commands or call the method cancelCommand() if the blocking method send() does not return.

Parameters:

ATCmd - The command to send.

Returns:

The complete answer of the device corresponding to the send command.

Throws:

ATCommandFailedException - if sending of the command fails because:

the response was too long to fit into the internal buffer

of some internal reasons

IllegalStateException - if sending of the command not possible because:

the instance is in transparent data mode

a blockimg AT command is still running

illegal instance state (e.g. released)

IllegalArgumentException - if the command is invalid because:

it exceeds the maximal possible length

it is an empty string

See Also:

send(String ATCmd, ATCommandResponseListener response)

send

public void send(String ATCmd,
                 ATCommandResponseListener response)
          throws ATCommandFailedException,
                 IllegalStateException,
                 IllegalArgumentException

Send an AT command to the device. There will be no interpretation of the command which means that the string to send should contain a valid command which will be understood by the module including the finalizing line feed "\r" or the corresponding line end character set in the S3 register! This is a non blocking function which means that the calling thread is continued immediately after the command has been sent to the module. The response is delivered later when it is available to the callback instance given in the second parameter. There is no internal queueing of subsequent calls to this or the blocking send function. This means that a call to any send function before a ongoing command has been finished and delivered the response will cancel that command! Alternatively the "cancelCommand" method can be used. Both can be used to e.g. cancel an ongoing atd command. Commands which are send in blocking mode can not be canceled!

Currently there are 1024 bytes reserved to temporary store the response internal inside the virtual machine. Some AT commands return responses which might be longer (e.g. reading a phone book or the provider list at once). In this case an ATCommandFailedException will be printed out (not thrown) and the callback class is called passing a null to the listener function. To avoid this an application should use the possible problematic commands in their format returning only single entries. Also if anything else went wrong the response listener is called with a null as parameter to indicate the problem. If already this send function throws an exception the listener is not called anymore.

Attention:
If there are strings sent to the AT command interpreter by this method which are not valid AT commands because they don't start with "AT" they will be ignored by the AT command interpreter, no response will be sent and the waiting listener will never be called! If an invalid AT command is cancelled with the cancelCommand() function the waiting response listener will be called with an "ERROR" as response.

Parameters:

ATCmd - The command to send.

response - Instance of the callback class which will receive the response to the command.

Throws:

ATCommandFailedException - if sending of the command fails because of some internal reasons

IllegalStateException - if sending of the command not possible because:

the instance is in transparent data mode

illegal instance state (e.g. released)

a blockimg AT command is still running

IllegalArgumentException - if the command is invalid because:

there is a no callback instance given

it exceeds the maximal possible length

it is an empty string

See Also:

send(String ATCmd), cancelCommand()

cancelCommand

public void cancelCommand()
                   throws ATCommandFailedException,
                          IllegalStateException

Cancel a running AT command. Possible result codes of the cancel process are sent to the waiting callback instance of the corresponding send method.

Throws:

ATCommandFailedException - if canceling command fails because of some internal reasons.

IllegalStateException - if canceling command fails because:

the instance is in transparent data mode

no AT command is currently running

illegal instance state (e.g. released)

See Also:

send(String ATCmd, ATCommandResponseListener response)

setDTR

public void setDTR(boolean SignalState)
            throws ATCommandFailedException

Set the state of the DTR (Data Terminal Ready) signal of the devices AT channel. The ATCommand class replaces the connection of the devices AT interpreters to an external device through a serial interface. So this function is therefore some kind of a virtualization of the DTR signal.

Parameters:

SignalState - The new state of the DTR signal.

Throws:

ATCommandFailedException - if setting of the DTR signal failed because of some internal reasons.

getRING

public boolean getRING()
                throws ATCommandFailedException

Get the state of the RING signal of the devices AT channel. The ATCommand class replaces the connection of the devices AT interpreters to an external device through a serial interface. So this function is therefore some kind of a virtualization of the RING signal. Additional changes of the signal will be reported to the ATCommandListener callback class.

Returns:

The current state of the RING signal.

Throws:

ATCommandFailedException - if reading of the RING signal fails because of some internal reasons.

See Also:

ATCommandListener, addListener(com.siemens.icm.io.ATCommandListener)

getDCD

public boolean getDCD()
               throws ATCommandFailedException

Get the state of the DCD (Data Carrier Detect) signal of the devices AT channel. The ATCommand class replaces the connection of the devices AT interpreters to an external device through a serial interface. So this function is therefore some kind of a virtualization of the DCD signal. Additional changes of the signal will be reported to the ATCommandListener callback class.

Returns:

The current state of the DCD signal.

Throws:

ATCommandFailedException - if reading of the DCD signal fails because of some internal reasons.

See Also:

ATCommandListener, addListener(com.siemens.icm.io.ATCommandListener)

getDSR

public boolean getDSR()
               throws ATCommandFailedException

Get the state of the DSR (Data Set Ready) signal of the devices AT channel. The ATCommand class replaces the connection of the devices AT interpreters to an external device through a serial interface. So this function is therefore some kind of a virtualization of the DSR signal. Additional changes of the signal will be reported to the ATCommandListener callback class.

Returns:

The current state of the DSR signal.

Throws:

ATCommandFailedException - if reading of the DSR signal fails because of some internal reasons.

See Also:

ATCommandListener, addListener(com.siemens.icm.io.ATCommandListener)

getCONN

public boolean getCONN()
                throws ATCommandFailedException

Get the state of a data connection of the devices AT channel. Additional changes of the signal will be reported to the ATCommandListener callback class.

Returns:

The current state of a data connection.

Throws:

ATCommandFailedException - if getting the state fails because of some internal reasons.

See Also:

ATCommandListener, addListener(com.siemens.icm.io.ATCommandListener)

csdSupported

public boolean csdSupported()

Get information if the connected AT-Interpreter is able to handle CSD connections.

Returns:

The data and fax capability of the connected instance of the device's AT interpreter.

addListener

public void addListener(ATCommandListener listener)

Registers listeners to receive unsolicited AT-Events (URCs). The listener object is an implementation of ATCommandListener interface. When associated to a specific instance ATCommand, this object's callback methods will be called each time when URCs or interface signal changes occur on the corresponding device AT-Interpreter. Registered listener instances are stored in an internal table but are not guaranteed to be called in the order they has been registered.

Parameters:

listener - The ATCommandListener object to be registered.

See Also:

ATCommandListener, removeListener(com.siemens.icm.io.ATCommandListener)

removeListener

public void removeListener(ATCommandListener listener)

Removes a listener object which has been previously added from the internal list table of listener objects. After it has been removed from the list it won't be called in case of unsolicited AT-Events (URCs) any more. If it hasn't been registered before the list will remain unchanged.

Parameters:

listener - The ATCommandListener object to be removed from the list.

See Also:

ATCommandListener, addListener(com.siemens.icm.io.ATCommandListener)

breakConnection

public String breakConnection()
                       throws IOException

This function switches the module, when in CSD data call, back from transparent data mode to AT command mode. Because the Java implementation of sending data to a data connection via the OutputStream doesn't support the usual way to switch the module back from transparent data mode to AT command mode with the "+++" sequence this function is the only way to leave the transparent data mode.

Before it is switched back to AT command mode the output buffer of the OutputStream will be flushed automatically. Possible pending read operations via the InputStream stream will return after the data connection has been closed.

Calling breakConnection() to stop an ongoing data transfer of another thread provokes an IOException.

This method is exclusive for CSD data calls. It cannot be called for other procedures using the data stream mode like I2C or RSA, which have their own way to change to AT command mode.

Returns:

The complete answer of the device corresponding to break command.

Throws:

IOException - if there is no open data connection available, the stream has been closed before or an IO error occurs.

See Also:

getDataInputStream(), getDataOutputStream()

getDataOutputStream

public OutputStream getDataOutputStream()

This function returns the output stream for data connections. Even if it implements the interface of the OutputStream class there are some slight differences:

If there are data connections created with the ATCommand class (typically with "ATD" or "AT^SSPI") this stream is used to send output data to the data connection. It is already open but accepts only data if the module is in transparanet data mode (an open data connection exists). If the module is in AT command mode calling of any function of this stream causes an IOException. The stream remains open until the release function of the ATCommand class is called. This means that the close() function of this stream hasn't any consequence. All write() functions return immediately if there is enough place in the send buffer. Only if not all data can be written in the out buffer they will block until there is enough place in the buffer again. The flush() function will block until all buffered data has been sent out. The write() and flush() functions are only able to access the internal used primary buffers. If data has left these primary buffers it might be possible that the data is still stored in lower buffers. These buffers cannot be accesed by the high level Java classes any more. So it might be possible that data in these lower buffers is lost when a data connection is closed even if the flush() function has been called and has successfully returned.

For performance reasons there is no synchronization done in this stream class. If an instance of this class has to be accessed from different threads it has to be ensured that the write() functions and the flush() function are synchronized in the user implementation.

Returns:

The output stream instance for data connections of this class instance.

See Also:

OutputStream, release()

getDataInputStream

public InputStream getDataInputStream()

This function returns the input stream for data connections. Even if it implements the interface of the InputStream class there are some slight differences:

If there are data connections created with the ATCommand class (typically with "ATD" or "AT^SSPI") this stream is used to read input data from the data connection. It is already open but can only be used if the module is in transparanet data mode (an open data connection exists). If the module is in AT command mode calling of any function of this stream causes an IOException. The stream remains open until the release function of the ATCommand class is called. This means that the close() function of this stream hasn't any consequence. Possible pending write() or skip() functions of this stream will return with the already read or skipped data or -1 in case of the single byte read() if the data connection is interrupted by calling the breakConnection() function. The mark feature of the InputStream class is not supported.

For performance reasons there is no synchronization done in this class. If an instance of this class has to be accessed from different threads it has to be ensured that the read() functions, the skip() function and the available() function are synchronized in the user implementation.

Returns:

The input stream instance for data connections of this class instance.

See Also:

InputStream, breakConnection()