Maxim Integrated 73M1822/73M1922 Modem API - Manual (Page 6)

73M1822/73M1922 Modem API User Guide UG_1x22_055
6 Rev. 1.0
1.1 Overview
The Modem API is a user-friendly programming conduit used to access and manage the modem
device/channel via the Reference Driver. This section describes the programming flow and how the
application program can be implemented using the Modem APIs.
First, the concept of device versus channel, the Teridian 73M1x22 Control module supports multiple
modem channels. The application layer communicates with the driver using this channel descriptor.
However, the driver reports asynchronous channel events through the device descriptor. At this point, the
only use for the device descriptor is for conveying event notification and for retrieving events from the
driver.
The application program must first initialize the Modem API by calling M1X22_MdmApiInit(). This
initializes internal data structures and prepares the API subsystem for subsequent call to other APIs.
After the Modem API is initialized, the application program opens the device and channel descriptors to
access and manage the device and channel(s) by calling M1X22_OpenDevice() and
M1X22_OpenChannel
() respectively. If more than one channel exists in the hardware platform, each
channel is opened separately by calling M1X22_OpenChannel().
To simplify the usage of the driver, the API encapsulates all relevant data components required to
operate the device and the channels into a data structure whose pointer is referred to as a “handle”. This
handle is returned from a successful call to open device/channel APIs and is used throughout the life of
the device and channels.
Upon exiting the application program it is recommended that all device and channels descriptors be
closed, using M1X22_CloseDevice() and M1X22_CloseChannel(), and the API subsystem be
shutdown using M1X22_MdmApiRelease() to ensure that the system resources are free up when the
application program terminates.
As mentioned earlier, the asynchronous events from each channel are reported through the opened
device descriptor. The event message contains the channel ID from which the event occurred on. The
application program must distinguish the event for each channel and act accordingly. The way this event
is conveyed to the application program is via the callback function provided as one of the parameter
passed in to the M1X22_OpenDevice(). The callback function serves as a “hook” for the API
subsystem and notifies the application whenever an event is generated.
Section 5 provides a sample application using the modem API.
1.2 Conventions Used in this Guide
This document uses the following conventions:
• Software code, IOCTL names and data types are presented in Courier font.
• A table with a blue header is a summary table. A table with a gray header is a detail table.
1.3 Acronyms
API – Application Programming Interface
APOH – Another Phone Off Hook
BSP – Board Support Package
DAA – Data Access Arrangement
IET – Interval Event Table
IOCTL – I/O Control
NOPOH – No Phone Off Hook
POH – Phone Off Hook