< 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 #####
<-> 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.
#### 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 #####
-> 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.
#### 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 #####
-> name | Pointer to the name of the profile to be deleted.
#### Result #####
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. ## New CncGetParamType #### Purpose Macro that returns the parameter type portion of the parameter ID. #### Prototype CncGetParamType (parameterID) #### Parameters #####
-> parameterID | A 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 #####
-> name | Pointer to the name of the profile to be returned. Passing in NULL causes this function to return the settings for the profile currently selected in the Connection panel.
#####
<- port | Pointer to the port identifier that the profile uses.
#####
<- baud | Pointer to the baud rate that has been set for this profile.
#####
<- volume | Pointer to the volume of the device (applies only to modems).
#####
<- handShake | Pointer to the flow control setting (hardware handshaking). 0 indicates automatic (on at speeds > 2400 baud), 1 indicates always on, and 2 indicates always off.
#####
<- initString | Pointer to the initialization string for the device (applies only to modems).
#####
<- resetString | Pointer to the reset string for the device (applies only to modems).
#####
<- isModem | Pointer to a Boolean value: true for Modem, false for Direct.
#####
<- isPulse | Pointer to a Boolean value: true for Pulse dial, false for TouchTone.
#### Result #####
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 #####
<- nameListPPP | Pointer to a pointer to a list of profile names.
#####
<- countP | Pointer 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 #####
-> parameterID | The 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 #####
-> parameterID | A 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 #####
-> parameterID | A 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 #####
-> parameterID | The 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 #####
-> parameterID | A 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 #####
-> parameterID | A 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 #####
-> parameterID | A 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 #####
<- profilesCountP | The 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 #####
<- profileIdP | Upon return, the unique ID of the new profile.
#### Result #####
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 ## New CncProfileDelete #### Purpose Deletes a profile. #### Prototype Err CncProfileDelete (CncProfileID profileId) #### Parameters #####
profileId | The 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 #####
<- profileIdP | The 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 #####
-> index | The index of the Connection Manager profile.
#####
<- profileIdP | The 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 #####
-> 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.
#### 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 #####
-> profileId | The profile ID.
#####
<- indexP | The 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 #####
-> profileId | The 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 #####
-> profileId | The ID of the profile from which to obtain a parameter value.
#####
-> paramId | The 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.
#####
<- 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.
#### 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 #####
-> iProfileId | The ID of the profile.
#####
-> paramId | The ID of the parameter. See "Profile Parameter Constants" 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 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 |