(68K) Connection Manager | Palm OS® Programmer's API Reference

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,
   UInt32 port,
   UInt32 baud,
   UInt16 volume,
   UInt16 handShake,
   const Char *initString,
   const 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. 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.

CncDeleteProfile Function ^TOP^

Purpose

Removes a profile from the Connection Manager.

Declared In

ConnectionMgr.h

Prototype

Err CncDeleteProfile (
   const Char *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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

CncProfileDelete Function ^TOP^

Purpose

Deletes a profile.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileDelete (
   CncProfileID profileId
)

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.

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.

CncProfileGetIDFromIndex Function ^TOP^

Purpose

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

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIDFromIndex (
   UInt16 index,
   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.

CncProfileGetIDFromName Function ^TOP^

Purpose

Returns the profile ID given its name.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIDFromName(
   const Char *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.

CncProfileGetIndex Function ^TOP^

Purpose

Returns the index of the profile given its ID.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileGetIndex (
   CncProfileID profileId,
   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.

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 (
   CncProfileID profileId
)

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.

CncProfileSettingGet Function ^TOP^

Purpose

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

Declared In

ConnectionMgr.h

Prototype

Err CncProfileSettingGet (
   CncProfileID profileId,
   UInt16 paramId,
   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.

CncProfileSettingSet Function ^TOP^

Purpose

Sets a parameter value in the specified profile.

Declared In

ConnectionMgr.h

Prototype

Err CncProfileSettingSet (
   CncProfileID iProfileId,
   UInt16 paramId,
   const void *paramBufferP,
   UInt16 paramSize
)

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.

61 Connection Manager

Connection Manager Data Types ^TOP^

CncProfileID Typedef ^TOP^

Purpose

Prototype

Compatibility

Connection Manager Constants ^TOP^

General Profile Parameters ^TOP^

Compatibility

Phone Profile Parameters ^TOP^

Purpose

Declared In

Constants

GPRS Profile Parameters ^TOP^

Purpose

Declared In

Constants

Profile Parameter Sizes ^TOP^

Compatibility

Profile Parameter Types ^TOP^

Purpose

Declared In

Constants

Compatibility

Device Kinds ^TOP^

Purpose

Declared In

Constants

Compatibility

Connection Manager Functions ^TOP^

CncAddProfile Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

Example

CncDefineParamID Macro ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

CncDeleteProfile Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

CncGetParamType Macro ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

See Also

CncGetProfileInfo Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

Example

CncGetProfileList Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments