(Page 1 of 1 in this chapter)

Chapter 2

Using the AGM Library

2.1 Introduction
2.2 The Lifetime of an AGM Context
2.3 Loading and Opening AG Device Drivers
2.4 Checking the AG Configuration File
2.5 Booting AG Boards
2.6 Downloading Boards
2.7 Monitoring AG Messages
2.8 Miscellaneous Functions
2.9 AGM Library Function Calling Sequence

2.1 Introduction

This chapter outlines the basic operations performed by an application using the AGM library and explains how the various AGM functions relate to one another.

2.2 The Lifetime of an AGM Context

The AGM processing context referenced and modified by the AGM library functions is identified by an AGM handle.

This AGM context is created by agmOpen, which returns an AGM handle to identify it. The AGM context is destroyed by agmClose, which renders the AGM handle invalid. The lifetime of an AGM context is referred to as a session.

The various agmOpen arguments determine the characteristics of the session. The most important argument is the configuration file. If no configuration file is specified, the session is opened in monitor mode.

Monitor mode is passive. In monitor mode, drivers do not have to be loaded - if there is anything to monitor, the drivers will already have been loaded - but the drivers must be opened. Furthermore, since there is no configuration, agmCheckConfig cannot be run, and no boards can be booted or downloaded.

2.3 Loading and Opening AG Device Drivers

The AG device drivers must be loaded and opened before the host can communicate with any hardware resources in the system. agmLoadDriver uses the configuration information in the AGM context to install and load the AG device drivers on the system. After the drivers have been loaded, agmOpenDriver can be used to open the AG device drivers. The mux handle returned by agmOpenDriver can be used to wait for messages coming up from the AG device driver.

2.4 Checking the AG Configuration File

After the AG device drivers have been loaded and opened, call agmCheckConfig to check the validity of the AG configuration file data before booting the boards. agmCheckConfig uses the opened AG device drivers to probe the hardware. Some of the information in the AGM context may be modified according to the actual hardware present in the system. Certain default files may be added to the lists of files to be downloaded to the boards if alternatives were not specified in the AG configuration file. A summary of the findings is written to the report file.

2.5 Booting AG Boards

agmBootBoard boots an AG board, runs diagnostics on it, and prepares it to receive downloaded files. Call agmBootBoard after the AG device drivers are loaded and opened, and after the configuration has been checked. agmBootBoard returns an AGM_BOOT_INFO structure containing status information as well as information read from the board's EEPROM. The first time each board is booted in a given session, a summary of the results is written to the report file.

2.6 Downloading Boards

The configuration file passed to agmOpen determines which files are to be downloaded to the board. agmDownloadBoard downloads the specified files to the AG board bound to the same AGM context. After successful downloading, an application can use the board for telephony functions. The first time any AG board is downloaded in a given session, a summary of the results is written to the report file (which was also specified in the call to agmOpen).

2.7 Monitoring AG Messages

Whenever a message comes up from the AG device driver, it is queued and the mux handle (returned by agmOpenDriver) is signaled. agmGetAGMessage retrieves an AG message from the queue. An application monitoring AG messages typically loops, waiting for the mux handle to be signaled, using a system call such as WaitForSingleObject or WaitForMultipleObjects (Windows NT) and poll (UNIX). Once the mux handle is signaled, the application calls agmGetAGMessage to retrieve the message and agmFormatAGMessage to transform it into a text string suitable for printing or logging.

2.8 Miscellaneous Functions

agmGetVersion returns the version number and the build date for the AGM library in a text string.

agmSignalMuxHandle is used to signal the mux handle to wake up any threads waiting on the handle by generating an artificial message and placing it in the queue. When agmGetAGMessage retrieves this message, it returns AGMERR_SIGNALLED instead of SUCCESS. This function is useful for waking up a thread that is waiting for the mux handle in operating systems that do not allow a wait on multiple wait objects.

2.9 AGM Library Function Calling Sequence

The following figure summarizes the order in which the AGM library functions should be called to maintain a consistent system state:

Figure 1. AGM Library Function Sequence











 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.