Connection Manager
 

 < Home   < Developers   < Development Support   < Documentation

57 Connection Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part III: Communications

57 Connection Manager

Connection Manager Data Types

CncProfileID

Connection Manager Constants

Profile Parameter Constants

Profile Parameter Size Constants

Device Kind Constants

Profile Parameter Types

Connection Manager Functions

CncAddProfile

CncDefineParamID

CncDeleteProfile

CncGetParamType

CncGetProfileInfo

CncGetProfileList

CncGetSystemFlagBitnum

CncGetTrueParamID

CncIsFixedLengthParamType

CncIsSystemFlags

CncIsSystemRange

CncIsThirdPartiesRange

CncIsVariableLengthParamType

CncProfileCloseDB

CncProfileCount

CncProfileCreate

CncProfileDelete

CncProfileGetCurrent

CncProfileGetIDFromIndex

CncProfileGetIDFromName

CncProfileGetIndex

CncProfileOpenDB

CncProfileSetCurrent

CncProfileSettingGet

CncProfileSettingSet

       

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:

Connection Manager Constants

Connection Manager Functions

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

New CncProfileID

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.

typedef UInt32 CncProfileID 

Compatibility

Defined only if Connection Manager Feature Set is present.

Connection Manager Constants

Profile Parameter Constants

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 Kind Constants.
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.
kCncParam_PSDCreator
UInt32
For phone profiles, the creator ID of the phone driver.
kCncParam_PSDName
string
For phone profiles, the name of the phone driver.
kCncParam_PSDParameter
Buffer
buffer
For phone profiles, a 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.
kCncParam_PSDType
UInt32
For phone profiles, the database type for the phone driver.
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.
kCncParamReceiveTimeOut
UInt32
For phone profiles, 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, the function TelNwkGetSelectedNetwork).
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.
kCncParamTTCreator
UInt32
For phone profiles, the creator ID of the telephony task used by the phone driver.
kCncParamTTType
UInt32
For phone profiles, the database type for the telephony task used by the phone driver.
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.

Profile Parameter Size Constants

The size constants specify the size of each of the predefined parameters described in "Profile Parameter Constants." 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

Compatibility

Defined only if Connection Manager Feature Set is present.

Device Kind Constants

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.

Constant
Value
Description
kCncDeviceKindSerial
0
The connection is through the serial port.
kCncDeviceKindModem
1
The connection is to a modem.
kCncDeviceKindPhone
2
The connection is to a phone.
kCncDeviceKindLocalNetwork
3
The connection is to a LAN.

Compatibility

Defined only if Connection Manager Feature Set is present.

Profile Parameter Types

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.

Constant
Value
Description
kCncParamSystemFlag
0x00
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.
kCncParamUInt8
0x01
A UInt8 parameter.
kCncParamUInt16
0x02
A UInt16 parameter.
kCncParamUInt32
0x03
A UInt32 parameter.
kCncParamString
0x04
A string parameter.
kCncParamBuffer
0x05
A generic block of data.

Compatibility

Defined only if Connection Manager Feature Set is present.

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, const Char *initString, const Char *resetString, Boolean isModem, Boolean isPulse)

Parameters

<-> namePointer 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.
-> portThe port identification used by the profile. See "Specifying the Port" of the Palm OS Programmer's Companion, vol. II, Communications for more information.
-> baudThe baud rate used by the profile.
-> volumeThe volume setting for the device (for Modem only).
-> handShakeFlow control setting (hardware handshaking). 0 specifies automatic (on at speeds > 2400 baud), 1 specifies always on, and 2 specifies always off.
-> initStringPointer to the initialization string used by a modem (for Modem only).
-> resetStringPointer to the reset string used by a modem (for Modem only).
-> isModemtrue if Modem, false if Direct.
-> isPulsetrue if Pulse dial, false if TouchTone.

Result

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

New CncDefineParamID

Purpose

Macro that creates and returns a parameter ID.

Prototype

CncDefineParamID (parameterRange, parameterType, parameterID)

Parameters

-> parameterRangeUse kCncParamThirdPartiesRange to specify that this parameter is not defined by the OS.
-> parameterTypeThe type of value stored for the parameter. See "Profile Parameter Types" for a list of possible values.
-> parameterIDA 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.

Result

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

Purpose

Removes a profile from the Connection Manager.

Prototype

Err CncDeleteProfile (const Char *name)

Parameters

-> namePointer to the name of the profile to be deleted.

Result

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

New CncGetParamType

Purpose

Macro that returns the parameter type portion of the parameter ID.

Prototype

CncGetParamType (parameterID)

Parameters

-> parameterIDA UInt16 that contains the parameter ID.

Result

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

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

-> namePointer 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.
<- portPointer to the port identifier that the profile uses.
<- baudPointer to the baud rate that has been set for this profile.
<- volumePointer to the volume of the device (applies only to modems).
<- handShakePointer to the flow control setting (hardware handshaking). 0 indicates automatic (on at speeds > 2400 baud), 1 indicates always on, and 2 indicates always off.
<- initStringPointer to the initialization string for the device (applies only to modems).
<- resetStringPointer to the reset string for the device (applies only to modems).
<- isModemPointer to a Boolean value: true for Modem, false for Direct.
<- isPulsePointer to a Boolean value: true for Pulse dial, false for TouchTone.

Result

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 "Profile Parameter Constants" 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

Purpose

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

Prototype

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

Parameters

<- nameListPPPPointer to a pointer to a list of profile names.
<- countPPointer to the number of profile names.

Result

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

New CncGetSystemFlagBitnum

Purpose

Macro that returns the number uniquely identifying a system flag parameter.

Prototype

CncGetSystemFlagBitnum (parameterID)

Parameters

-> parameterIDThe UInt16 containing the parameter ID.

Result

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

New CncGetTrueParamID

Purpose

Macro that returns the portion of the parameter ID that uniquely identifies the parameter.

Prototype

CncGetTrueParamID (parameterID)

Parameters

-> parameterIDA UInt16 containing the parameter ID.

Result

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

New CncIsFixedLengthParamType

Purpose

Macro that specifies whether the parameter value is fixed length or variable length.

Prototype

CncIsFixedLengthParamType (parameterID)

Parameters

-> parameterIDA UInt16 containing the parameter ID.

Result

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

New CncIsSystemFlags

Purpose

Macro that returns whether the parameter value is a system flag.

Prototype

CncIsSystemFlags (parameterID)

Parameters

-> parameterIDThe UInt16 containing the parameter ID.

Result

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

New CncIsSystemRange

Purpose

Macro that specifies whether the parameter is in the system range or in the third-party range.

Prototype

CncIsSystemRange (parameterID)

Parameters

-> parameterIDA UInt16 containing the parameter ID.

Result

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

New CncIsThirdPartiesRange

Purpose

Macro that specifies whether the parameter is defined by a third party.

Prototype

CncIsThirdPartiesRange (parameterID)

Parameters

-> parameterIDA UInt16 containing the parameter ID.

Result

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

New CncIsVariableLengthParamType

Purpose

Macro that returns whether the parameter value is a variable-length type.

Prototype

CncIsVariableLengthParamType (parameterID)

Parameters

-> parameterIDA UInt16 containing the parameter ID.

Result

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

New CncProfileCloseDB

Purpose

Closes the Connection Manager profile database.

Prototype

Err CncProfileCloseDB (void)

Parameters

None.

Result

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.

New CncProfileCount

Purpose

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

Prototype

Err CncProfileCount (UInt16 *profilesCountP)

Parameters

<- profilesCountPThe number of profiles.

Result

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

Compatibility

Implemented only if Connection Manager Feature Set is present.

See Also

CncGetProfileList

New CncProfileCreate

Purpose

Adds a profile record to the Connection Manager profile database.

Prototype

Err CncProfileCreate (CncProfileID *profileIdP)

Parameters

<- profileIdPUpon return, the unique ID of the new profile.

Result

errNone No error.
kCncErrDBAccessFailed The profile database could not be opened.
a Data Manager errorThe 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

New CncProfileDelete

Purpose

Deletes a profile.

Prototype

Err CncProfileDelete (CncProfileID profileId)

Parameters

profileIdThe ID of the profile to delete.

Result

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

New CncProfileGetCurrent

Purpose

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

Prototype

Err CncProfileGetCurrent (CncProfileID *profileIdP)

Parameters

<- profileIdPThe ID of the current profile.

Result

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

New CncProfileGetIDFromIndex

Purpose

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

Prototype

Err CncProfileGetIDFromIndex (UInt16 index, CncProfileID *profileIdP)

Parameters

-> indexThe index of the Connection Manager profile.
<- profileIdPThe ID of the Connection Manager profile.

Result

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

New CncProfileGetIDFromName

Purpose

Returns the profile ID given its name.

Prototype

Err CncProfileGetIDFromName (const Char *profileNameP, CncProfileID *profileIdP)

Parameters

-> profileNamePThe 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.
<- profileIdPThe profile ID.

Result

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

New CncProfileGetIndex

Purpose

Returns the index of the profile given its ID.

Prototype

Err CncProfileGetIndex (CncProfileID profileId, UInt16 *indexP)

Parameters

-> profileIdThe profile ID.
<- indexPThe index of the profile's record in the Connection Manager profile database.

Result

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

New CncProfileOpenDB

Purpose

Opens the Connection Manager profile database.

Prototype

Err CncProfileOpenDB (void)

Parameters

None

Result

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.

New CncProfileSetCurrent

Purpose

Sets the current profile.

Prototype

Err CncProfileSetCurrent (CncProfileID profileId)

Parameters

-> profileIdThe ID of the profile to be made current.

Result

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

New CncProfileSettingGet

Purpose

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

Prototype

Err CncProfileSettingGet (CncProfileID profileId, UInt16 paramId, void *paramBufferP, UInt16 *ioParamSizeP)

Parameters

-> profileIdThe ID of the profile from which to obtain a parameter value.
-> paramIdThe ID of the parameter to obtain. See "Profile Parameter Constants" for a list of the parameters used in the profiles that come preinstalled on the device.
<- paramBufferPA 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.
<-> ioParamSizePOn 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.

Result

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

New CncProfileSettingSet

Purpose

Sets a parameter value in the specified profile.

Prototype

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

Parameters

-> iProfileIdThe ID of the profile.
-> paramIdThe ID of the parameter. See "Profile Parameter Constants" for a list of the parameters defined in the preinstalled connection profiles.
-> paramBufferPA pointer to the value to set for this parameter.
-> paramSizeThe size of the buffer passed in paramBufferP. See "Profile Parameter Size Constants."

Result

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