This document introduces you to the ACM Server library. The ACM Server library is one element of the USB Manager OS component. More specifically it forms part of the suite of code that makes ACM (Abstract Control Module) functions available over a Universal Serial Bus; ACM functions can be used to provide serial port emulation over USB.
The ACM Server library provides an ACM class controller with a connection to the ACM server that runs inside ECACM.CSY.
Intended Audience
This document is for Symbian licensees who are implementing virtual serial port services on a Symbian device.
The ACM Server Library Details
The DLL that provides the functionality and the library to which your code must link are identified below.
The ACM Server library has only one kind of client, an ACM class controller. Symbian provide a reference implementation of an ACM class controller (acmclasscontroller.dll), and licensees are responsible for modifying, supplementing or replacing it to suit their requirements.
The ACM Server library is not itself the ACM server: it is an interface between the ACM class controller and the ACM server proper. The ACM server proper runs inside a C32 plug-in called ECACM.CSY.
The ACM server thus conforms to the standard Symbian "client-server" paradigm: in this case, a .CSY module contains the server and a .DLL module provides the interface that enables client code to interact with the server.
The ACM Server library enables an ACM class controller to control the number of ACM functions that a Symbian device presents to the USB host during enumeration. It also enables the ACM class controller to specify the protocol setting for each ACM function.
There is only one key class belonging to the ACM Server library: RAcmServer.
The ACM Server library provides the following categories of functionality to an ACM class controller:
Enables it to connect to (and disconnect from) the ACM server that runs inside ECACM.CSY.
Enables it to create and destroy a specified number of ACM functions.
Enables it to tell the ACM server which protocol setting to assign to an ACM function.
Establishing a connection between an ACM class controller and the ACM server
Before calling any of the other functions available from the ACM Server library, your ACM class controller must call the RAcmServer class's Connect() function. This starts the ACM server inside ECACM.CSY and establishes a connection between the ACM class controller and the ACM server.
To disconnect the ACM class controller from the ACM server, you need to use the RAcmServer class's Close() function. Note that you must destroy all ACM functions created by the ACM class controller before you disconnect it from the ACM server (see the next section).
Creating and destroying virtual serial ports (ACM functions)
To tell the ACM server how many ACM functions to create, you need to call the RAcmServer's CreateFunctions() function, specifying a value for the aNoAcms parameter. The maximum number of ACM functions that can exist concurrently is eight, assuming sufficient endpoints are available.
When you call the CreateFunctions() function without specifying an aProtocol argument (see the next section about specifying the protocol setting), the ACM server will assign the ACM function a protocol setting of 01h (hex) or 1 (dec).
To destroy a specified number of ACM functions, you need to use the RAcmServer's DestroyFunctions() function, specifying a value for the aNoAcms parameter. You cannot target particular ACM functions for destruction. Therefore you need to be aware that functions are destroyed on a Last-In-First-Out basis. In other words, the last ACM function to be created is the first one to be destroyed. Note that all ACM functions need to have been destroyed before the ACM class controller that created them is destroyed.
Telling the ACM server which protocol setting to assign to an ACM function
The protocol setting assigned to an ACM function determines the value of the "protocol" field in the interface descriptor for that ACM function's USB endpoint. It gives the USB host a way of deciding which piece of driver software to use to handle data transfers to and from the ACM function concerned. Symbian's default protocol setting of 01h for ACM functions tells the host to use the driver software for processing Hayes AT modem data.
If you want to use a different protocol setting from the default, you must supply an aProtocol argument when you call the RAcmServer's CreateFunctions() function (see previous section). The RAcmServer::CreateFunctions() function is overloaded to enable you to call it with either a single parameter (aNoAcms) or with two parameters (aNoAcms, aProtocol).