public interface ATDevice extends Peripheral<ATDevice>
ATDevice
interface provides methods for controlling a Data Communication Equipment
such as a modem or a cellular module using AT commands.
An AT device may be identified by the numerical ID, by the name (if any defined) and by an
optional set of capabilities (properties) that correspond to its registered configuration. An
ATDevice
instance can be opened by a call to one of the
PeripheralManager.open(id,...)
methods using its ID or by a
call to one of the
PeripheralManager.open(name,...)
methods using its name and capabilities. javax.deviceaccess.atcmd.config
,
javax.deviceaccess.atcmd.csd
, javax.deviceaccess.atcmd.psd
,
javax.deviceaccess.atcmd.voice
, javax.deviceaccess.atcmd.sms
,
javax.deviceaccess.atcmd.sim
, javax.deviceaccess.atcmd.phonebook
. Their meaning
is defined as follows:
javax.deviceaccess.atcmd.config
javax.deviceaccess.atcmd.csd
javax.deviceaccess.atcmd.psd
javax.deviceaccess.atcmd.voice
javax.deviceaccess.atcmd.sms
javax.deviceaccess.atcmd.sim
javax.deviceaccess.atcmd.phonebook
<keyword>=true
For example: javax.deviceaccess.atcmd.phonebook=true
. ATDevice
either synchronously or asynchronously. When
submitted synchronously using the sendCommand(String)
, the
response string will be available as the return value to the call. When submitted asynchronously
using the
sendCommand(String, CommandResponseHandler)
a CommandResponseHandler
instance must be
provided to handle the response when available.
Note that the command strings passed as parameter to the sendCommand
methods are the
complete AT command lines including the AT
prefix and a termination character.
An ATDevice
can only handle one command at a time. Commands cannot be sent (or queued)
while a command is already being handled. Nevertheless, if supported by the underlying AT device,
several commands may be concatenated in a single command line.
An ATDevice
may report responses that are either information text or result codes. A
result code can be one of three types: final, intermediate, and unsolicited. A final result code
(e.g; OK
or ERROR
) indicates the completion of command and the readiness for
accepting new commands. An intermediate result code (e.g. CONNECT
) is a report of the
progress of a command. An unsolicited result code (e.g. RING
) indicates the occurrence of
an event not directly associated with the issuance of a command. sendCommand(String)
method or as the parameter to the
processResponse
method of a CommandResponseHandler
instance provided as parameter
to a call to sendCommand(String, CommandResponseHandler)
. ATE0
command). processResponse
method of a
UnsolicitedResponseHandler
instance.
A data connection can be established by calling the openDataConnection
with a dedicated AT command such as ATD
. The state of the connection
can be monitored by additionally providing an DataConnectionHandler
instance.
When done, an application should call the close
method to close the AT device.
Any further attempt to use an ATDevice
instance which has been closed will result in a
ClosedPeripheralException
been thrown.
Opening an ATDevice
instance is subject to permission checks (see ATPermission
).
Note: The sendCommand
methods of ATDevice
do not parse the provided AT commands.
The AT command line should include the AT
prefix and the proper termination character
when and where needed.BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
Modifier and Type | Method and Description |
---|---|
void |
abortCommand(java.lang.String abortSequence)
Aborts the currently executing command by sending the provided
abortSequence . |
void |
close()
Closes this peripheral device, relinquishing the underlying peripheral device resource and
making it available to other applications.
|
void |
escapeToCommandMode()
When in data mode, calling this method will try to switch to command mode such as (depending
on the underlying AT device) by sending
"+++" escape sequence. |
int |
getMaxCommandLength()
Returns the maximum length of the command string that can be processed by the underlying AT
parser.
|
boolean |
isConnected()
Queries if this AT device has an opened data connection.
|
boolean |
isInCommandMode()
Queries if this AT device is in command mode.
|
DataConnection |
openDataConnection(java.lang.String cmd,
CommandResponseHandler crHandler,
DataConnectionHandler dcHandler)
Opens a data connection by issuing the specified AT command and optionally handles the
response and the opened connection asynchronously.
|
java.lang.String |
sendCommand(java.lang.String cmd)
Sends an AT command and wait for the response.
|
void |
sendCommand(java.lang.String cmd,
CommandResponseHandler handler)
Sends an AT command and handle the response asynchronously.
|
void |
setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler)
Registers a handler for handling Unsolicited Result Code responses.
|
getDescriptor, isOpen, tryLock, unlock
void abortCommand(java.lang.String abortSequence) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
abortSequence
.
Abortion depends on the command's definition (abortability). Calling this method does NOT
guarantee abortion of the currently executing command. It only aborts if the command supports
abortion and it is currently in a proper state for abortion.abortSequence
- the character sequence for aborting; if null
the ESC
(abort)
character is sent out by default.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.void escapeToCommandMode() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
"+++"
escape sequence.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.int getMaxCommandLength() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.boolean isConnected() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
true
if connected; false
otherwise.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.boolean isInCommandMode() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
true
if in command mode; false
otherwise.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.DataConnection openDataConnection(java.lang.String cmd, CommandResponseHandler crHandler, DataConnectionHandler dcHandler) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
CommandResponseHandler
and DataConnectionHandler
instances will be
invoked to handle respectively the response (error or intermediate and final result codes)
when available and the connection when opened then when subsequently closed.cmd
- the complete command line including the AT
prefix and the termination
character when and where needed.crHandler
- the CommandResponseHandler
instance to handle the response to the command
or null
if notification of specific error, intermediate and final response
codes are not requested.dcHandler
- the DataConnectionHandler
instance to handle the data connection or
null
if notification of connection state is not requested.null
if no data connection has been opened.java.lang.UnsupportedOperationException
- if opening data connections is not supported by this device.java.lang.IllegalStateException
- if in data mode or if a command is already being executed.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.SecurityException
- if the caller does not have the required permission.java.lang.String sendCommand(java.lang.String cmd) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
Ctrl-Z
otherwise the operation may block. In
which case it may be canceled by a call to abortCommand
. ATE0
command).cmd
- the complete command line including the AT
prefix and the termination
character when and where needed.java.lang.IllegalStateException
- if in data mode or if a command is already being executed.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.void sendCommand(java.lang.String cmd, CommandResponseHandler handler) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
CommandResponseHandler
instance will be invoked to handle the
response when available. The command line may or may not include payload text (such as SMS
body text); in which case the the provided CommandResponseHandler
instance will be
invoked to provide the additional input text (text prompt mode). If the command line includes
payload text, it must be properly terminated with e.g. Ctrl-Z
.cmd
- the complete command line including the AT
prefix and the termination
character when and where needed.handler
- the CommandResponseHandler
instance to handle the response to the command.java.lang.NullPointerException
- if cmd
or handler
is null
.java.lang.IllegalStateException
- if in data mode or if a command is already being executed.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.void setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
ATDevice
is open in PeripheralManager.SHARED
access mode the handlers
registered by all the applications sharing the underlying device will get invoked to handle
Unsolicited Result Code responses.
If handler
is null
then the previously registered handler will be removed.
Only one handler can be registered at a particular time.handler
- the UnsolicitedResponseHandler
instance to handle Unsolicited Result Code
responses.java.lang.NullPointerException
- if handler
is null
.java.lang.IllegalStateException
- if handler
is not null
and a handler is already registered.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
void close() throws java.io.IOException
Peripheral
instance will result
in a ClosedPeripheralException
being thrown.
This method has no effects if the peripheral device has already been closed.
Closing an ATDevice
will also close the device's DataConnection
.close
in interface java.lang.AutoCloseable
close
in interface java.nio.channels.Channel
close
in interface java.io.Closeable
close
in interface Peripheral<ATDevice>
java.io.IOException
- if some other I/O error occurs.Copyright © 2012, 2014, Oracle and/or its affiliates. All rights reserved.
Legal Notices