com.cinterion.io

Class ATCommand

java.lang.Object

com.cinterion.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 create more instances of this class will cause the constructor to fail.

Because the different AT-Channels of the device might have different capabilities, these capabilities 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 between the different character sets the class ATStringConversion can be used.

The usage of the short result code format as configured with "ATV0" is not possible when using the ATCommand class.

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.

See Also:

ATCommandListener, ATCommandResponseListener, ATStringConverter

Constructor Summary

Constructors

Constructor and Description
ATCommand(boolean csdSupport) 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. Please note that it is not possible to restore the state of an previously closed instance in a new instance of this class.
ATCommand(boolean csdSupport, long atResponseMaxSize) 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. Please note that it is not possible to restore the state of an previously closed instance in a new instance of this class.

Method Summary

Modifier and Type	Method and Description
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.
String	removeCharacter(String strResource, char chRemove)
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 strATCmd, ATCommandResponseListener Listener) 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

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

Constructor Detail

ATCommand

public ATCommand(boolean csdSupport)
          throws ATCommandFailedException

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.
Please note that it is not possible to restore the state of an previously closed instance in a new instance of this class. So if the release() function is called while e.g an issued AT command is still running and the response hasn't been received or a CSD connection is open a new created instance of this class will not work because the state of the underlaying AT command interpreter in the module is unknown. It is up to the user to ensure that the class instance is only released when there is no ongoing activity.

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 is 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, release()

ATCommand

public ATCommand(boolean csdSupport,
                 long atResponseMaxSize)
          throws ATCommandFailedException

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.
Please note that it is not possible to restore the state of an previously closed instance in a new instance of this class. So if the release() function is called while e.g an issued AT command is still running and the response hasn't been received or a CSD connection is open a new created instance of this class will not work because the state of the underlaying AT command interpreter in the module is unknown. It is up to the user to ensure that the class instance is only released when there is no ongoing activity.

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 is created. If CSD support is requested and there is no instance with CSD available an IllegalStateException will be thrown.

atResponseMaxSize - Maximum size of internal response buffer for method #send(String ATCmd). Setting value exceeds 1048576 (1Mbytes) to this parameter will be rounded to 1048576 (1Mbytes), and Setting value less than 61440 (60Kbytes) to 61440 (60Kbytes).

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, release()

Method Detail

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.cinterion.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()

cancelCommand

public void cancelCommand()
                   throws ATCommandFailedException

Cancel a running AT command. Possible result codes of the cancel process are sent to the waiting callback instance of the corresponding send method. Attention:
This is a blocking method and the caller of it will be blocked until the response with an "ERROR" of #send(String ATCmd, ATCommandResponseListener response) is listened, or until the response with an "ERROR" of #send(String ATCmd) is returned.

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
the instance has already been released
AT command is currently canceling

See Also:

send(String ATCmd, ATCommandResponseListener response)

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.

getCONN

public boolean getCONN()

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.

See Also:

ATCommandListener, addListener(com.cinterion.io.ATCommandListener)

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 read() 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.

To avoid additional copying of transferred data the read functions are directly mapped to the same native read function which serves also the AT command handling. To avoid locks of the internal state machine the user must always read all data available in transparent data mode.

Returns:

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

See Also:

InputStream, breakConnection()

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.

The call of this function blocks until all data has been handled by the native code. Because the data is buffered inside the radio stack before it is sent out to air it is possible that the function returns before the data has been left the module, though. Please note that the way of the data through the radio stack cannot be influenced any more after it has been left the write() function. So the flush() function is still available for backwards compatibility but has no effect any more.

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()

getDCD

public boolean getDCD()

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.

See Also:

ATCommandListener, addListener(com.cinterion.io.ATCommandListener)

getDSR

public boolean getDSR()

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.

See Also:

ATCommandListener, addListener(com.cinterion.io.ATCommandListener)

getRING

public boolean getRING()

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.

See Also:

ATCommandListener, addListener(com.cinterion.io.ATCommandListener)

release

public void release()
             throws IOException

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. Because the new instance has no possibility to query the last state it will then fail to work.

Throws:

IOException - if releasing locked resources fails because of some internal reasons

IllegalStateException - if releasing locked resources fails because of: illegal instance state (e.g. released) some internal reasons

removeCharacter

public String removeCharacter(String strResource,
                              char chRemove)

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.

Please note that the listener callback handling has been decoupled from the internal event loop to avoid deadlocks. This has been achieved by calling each waiting listener in a separate thread. For this reason it can occur that a waiting listener might be called once even after it has been already removed. This happens when the listener thread for the corresponding event has already been started before this function is called.

Parameters:

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

See Also:

ATCommandListener, addListener(com.cinterion.io.ATCommandListener)

send

public String send(String ATCmd)
            throws ATCommandFailedException

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.

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.

Continous commands which are delivering ongoing status information without ever ending or commands with very long responses are aborted after the internal response buffer has exceeded the default size (61440bytes) or the size set by #ATCommand(boolean csdSupport, long atResponseMaxSize) to avoid internal out of memory problems. If the usage of commands with oversized responses cannot be avoided the nonblocking send function must be used.

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:
of some internal reasons
AT command too long

IllegalStateException - if sending of the command not possible because:
the instance is in transparent data mode
an AT command is still running
the instance has already been released

IllegalArgumentException - if the command is invalid because:
it exceeds the maximal possible length
it is an empty string
it is a null object

See Also:

send(String, ATCommandResponseListener)

send

public void send(String strATCmd,
                 ATCommandResponseListener Listener)
          throws ATCommandFailedException

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 an ongoing command has been finished and delivered the response will cause an exception! Alternatively the "cancelCommand" method can be used.

If anything 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.

For continous commands which are delivering ongoing status information without ever ending or commands with very long reponses the response listener is called every time the internal response buffer has exceeded 1024 characters with the intermediate data. This is done until the command is caneceled or has finished.

Parameters:

strATCmd - The command to send.

Listener - 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
an AT command is still running
the instance has already been released

IllegalArgumentException - if the command is invalid because:
it exceeds the maximal possible length
it is an empty string
it is a null object

See Also:

send(String), cancelCommand()

setDTR

public void setDTR(boolean SignalState)
            throws IOException

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:

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