50 Connection Manager

The connection manager allows other applications to access, add, and delete connection profiles contained in the Connection Panel.

This chapter provides reference material for the connection manager API:

• Connection Manager Functions
  

The header file ConnectionMgr.h declares the connection manager API. For more information on the connection manager, see the chapter Serial Communication in the Palm OS Programmer's Companion.

Connection Manager Functions

CncAddProfile

Purpose

Adds a profile to the connection manager.

Prototype

Err CncAddProfile(Char *name, UInt32 port, UInt32 baud, UInt16 volume, UInt16 handShake, Char *initString, Char *resetString, Boolean isModem, Boolean isPulse)

Parameters

<-> name

Pointer to the profile name to be added. If the name is already taken in the Connection Panel then a duplication number is appended to it. The name added is returned here.

-> port

The port identification used by the profile.

-> baud

The baud rate used by the profile.

-> volume

The volume setting for the device (for Modem only).

-> handShake

Flow control setting (hardware handshaking). 0 specifies automatic (on at speeds > 2400 baud), 1 specifies always on, and 2 specifies always off.

-> initString

Pointer to the initialization string used by a modem (for Modem only).

-> resetString

Pointer to the reset string used by a modem (for Modem only).

-> isModem

true if Modem, false if Direct.

-> isPulse

true if Pulse dial, false if TouchTone.

Result

0	No error.
cncErrAddProfileFailed	The add operation failed.
cncErrProfileListFull	The add operation failed because the profile list is full.
cncErrConDBNotFound	The connection database is missing.

Comments

All profiles within the connection manager must have a unique name. The connection manager tries to append a duplication number to the end of the name if you specify a name that is already taken.

There is a maximum limit to the number of profiles that can be maintained by the connection manager. If the limit is passed, an error is returned and that profile will not be added. Profiles that do not need certain fields may pass 0 in the place of a value.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Example

AddMyProfile()

{
    Char *myConNameP;
    Err err;

    myConNameP = MemPtrNew(cncProfileNameSize);

    StrCopy(myConNameP, "Foobar");

    err = CncAddProfile(myConNameP, `u328', 57600, 0, 0, "AT&FX4", 0, true, false);

    MemPtrFree(myConNameP);
}

CncDeleteProfile

Purpose

Removes a profile from the connection manager.

Prototype

Err CncDeleteProfile(Char *name)

Parameters

-> name

Pointer to the name of the profile to be deleted.

Result

0	No error.
cncErrProfileReadOnly	The profile could not be deleted because it is read only.
cncErrProfileNotFound	The profile could not be found
cncErrConDBNotFound	The connection database is missing.

Comments

The profiles that come preinstalled on the unit are read only and cannot be deleted.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Example

void DeleteProfile(Char *name)

    {
    Err err;
    //Call Connection Manager to delete the
    //named profile
    err = CncDeleteProfile(name);
    }

CncGetProfileInfo

Purpose

Returns the settings for a profile.

Prototype

Err CncGetProfileInfo(Char *name, UInt32 *port, UInt32 *baud, UInt16 *volume, UInt16 *handShake, Char *initString, Char *resetString, Boolean * isModem, Boolean * isPulse)

Parameters

-> name

Pointer to the name of the profile to be returned. Passing in NULL causes this function to return the settings for the profile currently selected in the Connection Panel.

<- port

Pointer to the port identifier that the profile uses.

<- baud

Pointer to the baud rate that has been set for this profile.

<- volume

Pointer to the volume of the device (applies only to modems).

<- handShake

Pointer to the flow control setting (hardware handshaking). 0 indicates automatic (on at speeds > 2400 baud), 1 indicates always on, and 2 indicates always off.

<- initString

Pointer to the initialization string for the device (applies only to modems).

<- resetString

Pointer to the reset string for the device (applies only to modems).

<- isModem

Pointer to a Boolean value: true for Modem, false for Direct.

<- isPulse

Pointer to a Boolean value: true for Pulse dial, false for TouchTone.

Result

0	No error.
cncErrGetProfileFailed	The get profile operation failed. The profile may or may not be there.
cncErrProfileNotFound	The profile could not be found
cncErrConDBNotFound	The connection database is missing.

Comments

One or more of the parameters may be set to NULL if that information is not desired.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Example

    {

    UInt32 portID, baud;
    UInt16 openPort;
    // get port id
    err = CncGetProfileInfo("Direct Serial", &portID, &baud, 0, 0, 0, 0, 0, 0);
    if(!err)
    { // open the port
    SrmOpen(portID, baud, &openPort);
    }
    }

CncGetProfileList

Purpose

Returns a list of available profiles that are available through the connection manager.

Prototype

Err CncGetProfileList(Char *** nameListP, UInt16 * count)

Parameters

<- nameListP

Pointer to a pointer to a list of profile names.

<- count

Pointer to the number of profile names.

Result

0	No error.
cncErrGetProfileListFailed	The profile list could not be found.
cncErrConDBNotFound	The connection database is missing.

Comments

Allocation of the list is handled by the connection manager; deallocation is the responsibility of the calling application. Appended to the end of the list will be "-Current-", which represents the profile currently selected in the Connection Panel.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Example

    //Declared globally

    Char ** globalProfileList;
    ListType *listP;
    UInt16 globalProfileCount;

    void SetConnectionList()
    {
    //Get the list from the Connection Manager
    err = CncGetProfileList(&globalProfileList, &globalProfileCount);
    //Set the UI list
    LstSetListChoices(listP, globalProfileList, globalProfileCount);
    }

    void StopApplication()
    {
    UInt16 i;

    //Deallocate the connection list
    For(i = 0; i < globalProfileCount; i++)
    MemPtrFree(globalProfileList[ i ]);
    MemPtrFree(globalProfileList);
    }