Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

61    Connection Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 declared in the header file ConnectionMgr.h:

For more information on the Connection Manager, see the chapter "Serial Communication" in the Palm OS Programmer's Companion, vol. II, Communications.

Connection Manager Data Types ^TOP^

CncProfileID Typedef ^TOP^

Purpose

The CncProfileID type uniquely identifies a connection profile within the Connection Manager profile database. You pass this ID as a parameter to several of the Connection Manager functions. You can obtain a connection's profile ID using CncProfileGetIDFromName() or CncProfileGetIDFromIndex().

Prototype

typedef UInt32 CncProfileID;

Compatibility

Defined only if Connection Manager Feature Set is present.

Connection Manager Constants ^TOP^

General Profile Parameters ^TOP^

The Connection Manager defines the following constants to represent individual parameters in the preinstalled connection profiles. Not all parameters work for all types of profiles.

Parameter Name

Parameter
Type

Description

kCncParamBaud

UInt32

The baud rate to use for the connection.

kCncParamBluetoothDeviceAddr

buffer

The 48-bit address (BD_ADDR) of the device that the handheld is connected to through the Bluetooth port. This parameter is only valid if kCncParamPort specifies the Bluetooth port.

kCncParamBluetoothDeviceName

string

The name of the device that the handheld is connected to through the Bluetooth port. The device name uses the UTF-8 character encoding. This parameter is only valid if kCncParamPort specifies the Bluetooth port.

kCncParamCountryIndex

UInt16

The index into the list of strings returned by kCncParamIntlModemCountryStringList and kCncParamIntlModemResetStringList that provides the name of the country and the reset commands for this profile.

kCncParamDeviceKind

UInt16

The type of connection being made (general serial connection, connection to a modem, connection to a phone, and so on). This value is one of the Device Kinds.

kCncParamDialingMode

UInt8

For modem profiles, the dialing mode. 1 for Pulse dialing, 0 for TouchTone.

kCncParamFlowControl

UInt16

The flow control setting (hardware handshaking). 0 indicates that the flow control setting is enabled and disabled depending on the baud rate. If you choose this setting, flow control is on if the baud rate is greater than 2400. 1 indicates that flow control is always on, and 2 indicates that it is always off. This parameter does not apply to phone profiles.

kCncParamInitString

string

For modem and phone profiles, a null-terminated string containing the commands sent to initialize the connection. The Connection panel removes any carriage returns or other control characters from the initialization string before saving it to the profile.

kCncParamIntlModem
CountryStringList

buffer

For modem profiles, a data buffer containing a list of possible countries. This list contains the countries in which the modem can operate and is shown in the Connection panel Details form for this profile. The selected country controls the dialing prefix and the modem reset string. The kCncParamCountryIndex parameter specifies the country selected from this list.

The data buffer contains a packed block of null-terminated strings, each containing a country name. The first 16 bits of the data buffer (a UInt16 value) tells how many strings are contained in the block. You can use SysFormPointerArrayToStrings() to convert the data buffer into an array of strings.

Because this parameter value has a variable size, you must first call CncProfileSettingGet() with a NULL data pointer to obtain the correct size.

kCncParamIntlModem
ResetStringList

buffer

For modem profiles, a data buffer containing possible reset strings. The kCncParamCountryIndex parameter specifies which reset string from this list is to be used. The actual string used is itself stored in the kCncParamResetString parameter.

The data buffer contains a packed block of null-terminated strings, each containing a reset string. The first 16 bits of the data buffer (a UInt16 value) tells how many strings are contained in the block. You can use SysFormPointerArrayToStrings() to convert the data buffer into an array of strings.

Because this parameter value has a variable size, you must first call CncProfileSettingGet() with a NULL data pointer to obtain the correct size.

kCncParamInvisible

system flag

If true, the profile is hidden from the user. If false, the profile is visible. This parameter is not currently used.

kCncParamLocked

system flag

If true, the profile is locked so that the user cannot edit it. If false, the profile can be edited. This parameter can be set by profiles, such as phone profiles, created by third party utilities.

kCncParamName

string

The name of the profile.

kCncParamNoDetails

system flag

If true, the profile details should not be displayed. If false, they can be displayed. The profile details are the parameters that appear in the Details form of the Connection panel.

kCncParamNonEditable

system flag

If true, the Connection panel's Edit form should be suppressed for this profile. If false, the Edit form can be displayed.

This parameter differs from kCncParamLocked and kCncParamReadOnly in that it causes an alert to be displayed if the user taps the Edit button. The other parameters allow the Edit form to be displayed but do not allow changes to be made. Also, a non-editable profile can be deleted, but a read-only or locked profile cannot.

kCncParamPort

UInt32

The logical, physical, or virtual port identifier. See "Port Constants" in the "Serial Manager" chapter for more information.

kCncParamReadOnly

system flag

If true, the profile is read-only and cannot be edited. If false, the profile can be edited. This parameter is only intended to be used by profiles pre-installed in the Palm OS.

kCncParamResetString

string

For modem and phone profiles, the reset string. For modem profiles, this is one of the strings in kCncParamIntlModemResetStringList.

kCncParamSerialPortFlags

UInt32

For phone profiles, bit flags that correspond to various serial port hardware settings. See "Serial Settings Constants" for more information.

kCncParamSystemFlags

UInt32

A bit flag representing all system flags. Currently, only bits 0 through 4 have a meaning. These correspond to the read-only bit, the invisible bit, the noneditable bit, the no details bit, and the locked bit, respectively.

kCncParamTimeOut

UInt32

The amount of time in milliseconds to wait for a response when CTS is unasserted and hardware flow control is on.

kCncParamVersion

UInt8

The version of the Connection Manager API under which this profile was created. The current version number is kCncProfileVersion.

kCncParamVolume

UInt16

For modem profiles, the modem volume.

Compatibility

Defined only if Connection Manager Feature Set is present.

Phone Profile Parameters ^TOP^

Purpose

The Connection Manager defines the following constants to represent individual parameters in the preinstalled connection profiles for phones. Also see "General Profile Parameters" and "GPRS Profile Parameters" for other parameter constants that may apply.

Declared In

ConnectionMgr.h

Constants

#define kCncParamReceiveTimeOut CncDefineParamID( kCncParamOSRange , kCncParamUInt32, 14 )
A UInt32 containing the number of milliseconds to wait for a response from the phone. This time-out value is used by telephony functions that don't need to access the network (for example, TelNwkGetSelectedNetwork()).
#define kCncParamTTCreator CncDefineParamID( kCncParamOSRange, kCncParamUInt32, 91 )
A UInt32 containing the creator ID for the telephony task used by the phone driver.
#define kCncParamTTType CncDefineParamID( kCncParamOSRange, kCncParamUInt32, 90 )
A UInt32 containing the database type for the telephony task used by the phone driver.
#define kCncParam_GSM_BearerServices CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 211 )
#define kCncParam_GSM_ConnectionElement CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 212 )
#define kCncParam_GSM_Speed CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 210 )
#define kCncParam_PSDCreator CncDefineParamID( kCncParamOSRange, kCncParamUInt32, 93 )
A UInt32.containing the creator ID of the phone driver.
#define kCncParam_PSDName CncDefineParamID( kCncParamOSRange, kCncParamString, 92 )
A string containing the name of the phone driver.
#define kCncParam_PSDParameterBuffer CncDefineParamID(kCncParamOSRange, kCncParamBuffer, 100 )
Aa data buffer containing any necessary data that the phone driver needs to store. This parameter typically holds data that is set using the Details form of the Connection panel.
#define kCncParam_PSDType CncDefineParamID(kCncParamOSRange, kCncParamUInt32, 94 )
A UInt32.containing the database type for the phone driver.

GPRS Profile Parameters ^TOP^

Purpose

The Connection Manager defines the following constants to represent individual parameters in the preinstalled connection profiles for GPRS networks. Also see "General Profile Parameters" and "Phone Profile Parameters" for other parameter constants that may apply.

Declared In

ConnectionMgr.h

Constants

#define kCncParam_GPRS_APNName CncDefineParamID(kCncParamOSRange, kCncParamString, 200 )
A string containing the GPRS access point name (APN).
#define kCncParam_GPRS_DataCompression CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 202 )
A boolean value, stored in a UInt8, indicating data compression.
#define kCncParam_GPRS_HeaderCompression CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 201 )
A boolean value, stored in a UInt8, indicating header compression.
#define kCncParam_GPRS_QOS_Delay CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 204 )
A UInt8 containing the GPRS quality-of-service delay value.
#define kCncParam_GPRS_QOS_Mean CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 207 )
A UInt8 containing the GPRS quality-of-service mean throughput.
#define kCncParam_GPRS_QOS_Peak CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 206 )
A UInt8 containing the GPRS quality-of-service peak throughput.
#define kCncParam_GPRS_QOS_Precedence CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 203 )
A UInt8 containing the GPRS quality-of-service precedence value.
#define kCncParam_GPRS_QOS_Reliability CncDefineParamID(kCncParamOSRange, kCncParamUInt8, 205 )
A UInt8 containing the GPRS quality-of-service reliability value.

Profile Parameter Sizes ^TOP^

The size constants specify the size of each of the predefined parameters described in "General Profile Parameters." The following table lists the parameter name, the size of its value, and the size constant that gives this size. These size constants are suitable for passing to CncProfileSettingGet() and CncProfileSettingSet().

Profile Parameter Name

Size

Size Constant

kCncParamBaud

32

kCncParamBaudSize

kCncParamBluetoothDevice
Addr

8

kCncParamBluetoothDeviceAddrSize

kCncParamBluetoothDevice
Name

249

kCncParamBluetoothDeviceNameMaxSize

kCncParamCountryIndex

16

kCncParamCountryIndexSize

kCncParamDeviceKind

16

kCncParamDeviceKindSize

kCncParamDialingMode

8

kCncParamDialingModeSize

kCncParamFlowControl

16

kCncParamFlowControlSize

kCncParamInitString

81

kCncParamInitStringMaxSize

81

kCncProfileUsualInitStringSize

kCncParamInvisible

8

kCncParamInvisibleSize

kCncParamLocked

8

kCncParamLockedSize

kCncParamName

22

kCncParamNameMaxSize

22

kCncProfileNameSize

kCncParamNoDetails

8

kCncParamNoDetailsSize

kCncParamNonEditable

8

kCncParamNonEditableSize

kCncParamPort

32

kCncParamPortSize

kCncParam_PSDCreator

32

kCncParam_PSDCreatorSize

kCncParam_PSDName

32

kCncParam_PSDNameSize

kCncParam_PSDType

32

kCncParam_PSDTypeSize

kCncParamReadOnly

8

kCncParamReadOnlySize

kCncParamReceiveTimeOut

32

kCncParamReceiveTimeOutSize

kCncParamResetString

81

kCncParamResetStringMaxSize

8

kCncProfileClassicResetStringSize

81

kCncProfileUsualResetStringSize

kCncParamSystemFlags

32

kCncParamSystemFlagsSize

kCncParamTimeOut

32

kCncParamTimeOutSize

kCncParamTTCreator

32

kCncParamTTCreatorSize

kCncParamTTType

32

kCncParamTTTypeSize

kCncParamVersion

8

kCncParamVersionSize

kCncParamVolume

16

kCncParamVolumeSize

kCncParam_GPRS_APNName

kCncParam_GPRS_APNNameMaxSize (this is the maximum size that the APN name string may have).

kCncParam_GPRS_DataCompression

8

kCncParam_GPRS_DataCompressionSize

kCncParam_GPRS_HeaderCompression

8

kCncParam_GPRS_HeaderCompressionSize

kCncParam_GPRS_QOS_Delay

8

kCncParam_GPRS_QOS_DelaySize

kCncParam_GPRS_QOS_Mean

8

kCncParam_GPRS_QOS_MeanSize

kCncParam_GPRS_QOS_Peak

8

kCncParam_GPRS_QOS_PeakSize

kCncParam_GPRS_QOS_Precedence

8

kCncParam_GPRS_QOS_PrecedenceSize

kCncParam_GPRS_QOS_Reliability

8

kCncParam_GPRS_QOS_ReliabilitySize

kCncParam_GSM_BearerServices

8

kCncParam_GSM_BearerServicesSize

kCncParam_GSM_ConnectionElement

8

kCncParam_GSM_ConnectionElementSize

kCncParam_GSM_Speed

8

kCncParam_GSM_SpeedSize

Compatibility

Defined only if Connection Manager Feature Set is present.

Profile Parameter Types ^TOP^

Purpose

The parameter type constants specify the type of value stored for a parameter in a connection profile. If you define a new parameter using CncDefineParamID(), you must use one of these constants to specify the type of data the parameter stores. The macro CncGetParamType() can return this information for any parameter in the profile.

Declared In

ConnectionMgr.h

Constants

#define kCncParamBuffer CncDefineParameterType(kCncParamVariableLen, 2)
A generic block of data.
#define kCncParamString CncDefineParameterType(kCncParamVariableLen, 1)
A string parameter.
#define kCncParamSystemFlag CncDefineParameterType(kCncParamFixedLen, 0)
A system flag parameter. The Connection Manager can store up to 32 system flags. Flags are stored in a single bit and returned as a UInt8 value. The entire system flags word can be returned if you pass kCncParamSystemFlags to CncProfileSettingGet().
#define kCncParamUInt16 CncDefineParameterType(kCncParamFixedLen, 2)
A UInt16 parameter.
#define kCncParamUInt32 CncDefineParameterType(kCncParamFixedLen, 3)
A UInt32 parameter.
#define kCncParamUInt8 CncDefineParameterType(kCncParamFixedLen, 1)
A UInt8 parameter.

Compatibility

Defined only if Connection Manager Feature Set is present.

Device Kinds ^TOP^

Purpose

The device kind constants specify the type of connection being made. You specify the type of connection by defining a value for the kCncParamDeviceKind parameter using CncProfileSettingSet().

Declared In

ConnectionMgr.h

Constants

#define kCncDeviceKindGPRS 4
The connection is to a GPRS network.
#define kCncDeviceKindGSM 5
The connection is to GSM phone.
#define kCncDeviceKindLocalNetwork 3
The connection is to a LAN.
#define kCncDeviceKindModem 1
The connection is to a modem.
#define kCncDeviceKindPhone 2
The connection is to a phone.
#define kCncDeviceKindSerial 0
The connection is through the serial port.

Compatibility

Defined only if Connection Manager Feature Set is present.

Connection Manager Functions ^TOP^

CncAddProfile Function ^TOP^

Purpose

Adds a profile to the Connection Manager.

Declared In

ConnectionMgr.h

Prototype

Err CncAddProfile (
   Char*name,
   UInt32port,
   UInt32baud,
   UInt16volume,
   UInt16handShake,
   constChar*initString,
   constChar*resetString,
   BooleanisModem,
   BooleanisPulse
)

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. See "Specifying the Port" of the Palm OS Programmer's Companion, vol. II, Communications for more information.
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.

Returns

errNone
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 NULL in the place of a value.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

If Connection Manager Feature Set is present, use CncProfileCreate() instead of using this function. CncAddProfile is still supported for backward compatibility. In Palm OS 4.0 and higher, the maximum number of profiles that can be defined has greatly increased.

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); }

CncDefineParamID Macro ^TOP^

Purpose

Creates and returns a parameter ID.

Declared In

ConnectionMgr.h

Prototype

#define CncDefineParamID (
   parameterRange,
   parameterType,
   parameterID
)

Parameters

parameterRange
Use kCncParamThirdPartiesRange to specify that this parameter is not defined by the OS.
parameterType
The type of value stored for the parameter. See "Profile Parameter Types" for a list of possible values.
parameterID
A unique value between 0 to 1023. The value must be unique within the profile for which you are defining the parameter.
If you are using a parameterType of kCncParamSystemFlag, specify a value from 0 to 31 to identify which of the system flag bit is to be set.

Returns

Returns the parameter ID as a UInt16 value.

Comments

You use this macro only if you are defining your own connection profile and have a parameter that you need to define within that profile. The parameter ID immediately precedes its parameter value in the Connection Manager profile database. Because of how the database is formatted, the parameter ID must tell the Connection Manager how to interpret the next series of bytes. For this reason, the high order bits of the parameter ID include information about the type of value and whether the value is defined by the system or a third party.

Compatibility

Parameter IDs of this format are only used if 4.0 New Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncDeleteProfile Function ^TOP^

Purpose

Removes a profile from the Connection Manager.

Declared In

ConnectionMgr.h

Prototype

Err CncDeleteProfile (
   constChar*name
)

Parameters

name
Pointer to the name of the profile to be deleted.

Returns

errNone
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.

If Connection Manager Feature Set is present, use CncProfileDelete() instead of using this function.

CncGetParamType Macro ^TOP^

Purpose

Returns the parameter type portion of the parameter ID.

Declared In

ConnectionMgr.h

Prototype

#define CncGetParamType (
   parameterID
)

Parameters

parameterID
A UInt16 that contains the parameter ID.

Returns

Returns a UInt16 value where bits 11 through 14 contain one of the values in "Profile Parameter Types" and the other bits are clear.

Compatibility

Parameter IDs of this format are only used if 4.0 New Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncGetProfileInfo Function ^TOP^

Purpose

Returns the settings for a profile.

Declared In

ConnectionMgr.h

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.

Returns

errNone
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.

If Connection Manager Feature Set is present, use CncProfileSettingGet() with one of the "General Profile Parameters" instead of using this function.

Example

{ UInt32portID, baud; UInt16openPort; // 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 Function ^TOP^

Purpose

Returns a list of available profiles that are available through the Connection Manager.

Declared In

ConnectionMgr.h

Prototype

Err CncGetProfileList (
   Char***nameListPPP,
   UInt16*countP
)

Parameters

nameListPPP
Pointer to a pointer to a list of profile names.
countP
Pointer to the number of profile names.

Returns

errNone
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); }

CncGetSystemFlagBitnum Macro ^TOP^

Purpose

Returns the number uniquely identifying a system flag parameter.

Declared In

ConnectionMgr.h

Prototype

#define CncGetSystemFlagBitnum (
   parameterID
)

Parameters

parameterID
The UInt16 containing the parameter ID.

Returns

Returns the ID of the system flag parameter, which is a value from 0 to 31.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncGetTrueParamID Macro ^TOP^

Purpose

Returns the portion of the parameter ID that uniquely identifies the parameter.

Declared In

ConnectionMgr.h

Prototype

#define CncGetTrueParamID (
   parameterID
)

Parameters

parameterID
A UInt16 containing the parameter ID.

Returns

Returns a UInt16 containing just the parameter ID. The high-order bits, which specify the parameter type and address space, are clear.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncIsFixedLengthParamType Macro ^TOP^

Purpose

Specifies whether the parameter value is fixed length or variable length.

Declared In

ConnectionMgr.h

Prototype

#define CncIsFixedLengthParamType (
   parameterID
)

Parameters

parameterID
A UInt16 containing the parameter ID.

Returns

Returns true if the parameter is a fixed length parameter type such as UInt32, or false if it is a variable length type.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncIsSystemFlags Macro ^TOP^

Purpose

Returns whether the parameter value is a system flag.

Declared In

ConnectionMgr.h

Prototype

#define CncIsSystemFlags (
   parameterID
)

Parameters

parameterID
The UInt16 containing the parameter ID.

Returns

Returns true if the parameter type is a system flag. Returns false otherwise.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncIsSystemRange Macro ^TOP^

Purpose

Specifies whether the parameter is in the system range or in the third-party range.

Declared In

ConnectionMgr.h

Prototype

#define CncIsSystemRange (
   parameterID
)

Parameters

parameterID
A UInt16 containing the parameter ID.

Returns

Returns true if the parameter ID is defined by Palm OS, or false if it is defined by a third party.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncIsThirdPartiesRange Macro ^TOP^

Purpose

Specifies whether the parameter is defined by a third party.

Declared In

ConnectionMgr.h

Prototype

#define CncIsThirdPartiesRange (
   parameterID
)

Parameters

parameterID
A UInt16 containing the parameter ID.

Returns

Returns true if the parameter is a third-party parameter, or false if it is a system parameter.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncIsVariableLengthParamType Macro ^TOP^

Purpose

Returns whether the parameter value is a variable-length type.

Declared In

ConnectionMgr.h

Prototype

#define CncIsVariableLengthParamType (
   parameterID
)

Parameters

parameterID
A UInt16 containing the parameter ID.

Returns

Returns true if the parameter is a variable-length string or a buffer or false if it holds a fixed-length type such as an integer.

Compatibility

Parameter IDs of this format are only used if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncProfileSettingGet()

CncProfileCloseDB Function ^TOP^

Purpose

Closes the Connection Manager profile database.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileCloseDB (
   void
)

Parameters

None.

Returns

errNone
No error.
kCncErrDBAccessFailed
The database could not be closed or this is a reference counting error.

Comments

Use CncProfileOpenDB() and CncProfileCloseDB as an optimization if you make several Connection Manager calls in succession. All Connection Manager calls open the profile database when they begin and close the database when they are finished. The Connection Manager maintains a reference count that tells it whether the database is open. If you call CncProfileOpenDB before making another Connection Manager call, the next call does not open or close the database. This saves your application the overhead of opening and closing the database each time a call is made.

Compatibility

Implemented only if Connection Manager Feature Set is present.

CncProfileCount Function ^TOP^

Purpose

Returns the number of connection profiles currently defined in the Connection Manager profile database.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileCount (
   UInt16*profilesCountP
)

Parameters

profilesCountP
The number of profiles.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncGetProfileList()

CncProfileCreate Function ^TOP^

Purpose

Adds a profile record to the Connection Manager profile database.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileCreate (
   CncProfileID*profileIdP
)

Parameters

profileIdP
Upon return, the unique ID of the new profile.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
a Data Manager error
The new record could not be created.

Comments

This function creates a new empty record in the Connection Manager profile database. To populate the profile, use CncProfileSettingSet() to set parameter values, including the profile name. Use CncDefineParamID() if you need to store information unique to your profile.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncAddProfile(), CncProfileDelete()

CncProfileDelete Function ^TOP^

Purpose

Deletes a profile.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileDelete (
   CncProfileIDprofileId
)

Parameters

profileId
The ID of the profile to delete.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened, or the record could not be deleted.
kCncErrProfileParamNotFound
The database does not contain a profile with the specified ID.

Comments

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

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncDeleteProfile(), CncProfileCreate()

CncProfileGetCurrent Function ^TOP^

Purpose

Returns the ID of the currently selected profile in the Connection panel.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetCurrent(
   CncProfileID*profileIdP
)

Parameters

profileIdP
The ID of the current profile.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileGetIDFromIndex(), CncProfileGetIDFromName(), CncProfileGetIndex(), CncProfileSetCurrent()

CncProfileGetIDFromIndex Function ^TOP^

Purpose

Returns the profile ID given its index into the Connection Manager profile database.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIDFromIndex (
   UInt16index,
   CncProfileID*profileIdP
)

Parameters

index
The index of the Connection Manager profile.
profileIdP
The ID of the Connection Manager profile.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
kCncErrProfileParamNotFound
No profile at that index.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileGetIDFromName(), CncProfileGetCurrent(), CncProfileGetIndex()

CncProfileGetIDFromName Function ^TOP^

Purpose

Returns the profile ID given its name.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIDFromName(
   constChar*profileNameP,
   CncProfileID*profileIdP
) 

Parameters

profileNameP
The name of the profile. The name is displayed in a pop-up list in the Connection panel. If you pass the string "-Current-", this function returns the ID of the current profile.
profileIdP
The profile ID.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
kCncErrProfileParamNotFound
No profile with the specified name.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileGetCurrent(), CncProfileGetIDFromIndex(), CncProfileGetIndex()

CncProfileGetIndex Function ^TOP^

Purpose

Returns the index of the profile given its ID.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIndex (
   CncProfileIDprofileId,
   UInt16*indexP
) 

Parameters

profileId
The profile ID.
indexP
The index of the profile's record in the Connection Manager profile database.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
kCncErrProfileParamNotFound
No profile with the specified ID.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileGetIDFromIndex()

CncProfileOpenDB Function ^TOP^

Purpose

Opens the Connection Manager profile database.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileOpenDB (
   void
)

Parameters

None

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.

Comments

Use CncProfileOpenDB and CncProfileCloseDB() as an optimization if you make several Connection Manager calls in succession. All Connection Manager calls open the profile database when they begin and close the database when they are finished. The Connection Manager maintains a reference count that tells it whether the database is open. If you call CncProfileOpenDB before making another Connection Manager call, the next call does not open or close the database. This saves your application the overhead of opening and closing the database each time a call is made.

The Connection Manager profile database is created if it does not exist.

Compatibility

Implemented only if Connection Manager Feature Set is present.

CncProfileSetCurrent Function ^TOP^

Purpose

Sets the current profile.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileSetCurrent (
   CncProfileIDprofileId
)

Parameters

profileId
The ID of the profile to be made current.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.

Comments

The current profile is the profile that is used for the next network connection attempt.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileGetCurrent()

CncProfileSettingGet Function ^TOP^

Purpose

Obtains a value stored in one of the Connection Manager profiles.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileSettingGet (
   CncProfileIDprofileId,
   UInt16paramId,
   void*paramBufferP,
   UInt16*ioParamSizeP
)

Parameters

profileId
The ID of the profile from which to obtain a parameter value.
paramId
The ID of the parameter to obtain. See "General Profile Parameters" for a list of the parameters used in the profiles that come preinstalled on the device.
paramBufferP
A pointer to a buffer into which to write the parameter value. If the parameter stores a variable-sized value, you can determine the necessary size by passing NULL for paramBufferP. Upon return, paramSize contains the required size.
ioParamSizeP
On input, a pointer to the size of the buffer into which to write the parameter. On output, points to the number of bytes written to paramBufferP.

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
kCncErrProfileGetParamFailed
The Connection Manager failed to obtain the value of the parameter.
kCncErrProfileBadSystemFlagBitnum
An attempt was made to obtain the value of a system flag that is undefined.
kCncErrProfileBadParamSize
The paramBufferP buffer is too small. ioParamSizeP contains the correct size for the buffer.
kCncErrProfileParamNotFound
The specified parameter is not defined in the profile.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncProfileSettingSet(), CncGetProfileInfo()

CncProfileSettingSet Function ^TOP^

Purpose

Sets a parameter value in the specified profile.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileSettingSet (
   CncProfileIDiProfileId,
   UInt16paramId,
   constvoid*paramBufferP,
   UInt16paramSize
)

Parameters

iProfileId
The ID of the profile.
paramId
The ID of the parameter. See "General Profile Parameters" for a list of the parameters defined in the preinstalled connection profiles.
paramBufferP
A pointer to the value to set for this parameter.
paramSize
The size of the buffer passed in paramBufferP. See "Profile Parameter Sizes."

Returns

errNone
No error.
kCncErrDBAccessFailed
The profile database could not be opened.
kCncErrProfileParamNotFound
No profile with the specified ID.
kCncErrProfileSetParamFailed
The Connection Manager failed to set the value of the parameter.
kCncErrProfileBadParamSize
The paramBufferP buffer is too small. Most likely, the passed in size does not allow space for a string parameter's null terminator.
kCncErrProfileParamNameHasChange
An attempt was made to set the profile name to a name that is already used. The Connection Manager appends a duplication number to the end of the name and returns this error. You should use CncProfileSettingGet() to find out the new name.

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncDefineParamID(), CncProfileSettingGet()