The Connection Manager API provides a central mechanism for managing Palm OS® communications connections at a high level. This chapter contains the following sections that describe how to use the Palm OS Connection Manager:
- "About the Connection Manager," explains concepts you need to know before you can begin using the Connection Manager.
- "Using the Connection Manager," describes how to use the functions in the Connection Manager to accomplish common tasks.
For information about the built-in Connection Manager plug-ins, see Chapter 2, "Connection Manager Plug-ins."
For detailed information about Connection Manager data types, constants, and functions, see Chapter 3, "Connection Manager Reference."
About the Connection Manager
This section explains concepts you need to know before you can begin using the Connection Manager. It discusses the following topics:
- Overview
- Terminology
- Connection Profiles
- Security Considerations
- Persistent Connections
- Graph Management
Overview
The Connection Manager manages at a high level all connections from the Palm Powered™ handheld to external devices. Figure 1.1 shows how the Connection Manager interacts with other components in the communications system.
Figure 1.1 Connection Manager architecture

Communications components are installed in the Palm OS in the form of Connection Manager plug-ins, which handle the work of making, maintaining, and terminating communications connections at a low level. A Connection Manager plug-in is a piece of code that is responsible for configuring and connecting one or more communications components that implement one or more protocols. A plug-in also contains the user interface parts that are necessary to configure its components. Examples of plug-ins include Bluetooth, TCP/IP, PPP, USB, and IrDA.
Connection Manager plug-ins are built on the IOS (Input/Output Subsystem) framework and typically make use of lower-level IOS drivers and modules. Connection Manager plug-ins that are built into the Palm OS are described in Chapter 2, "Connection Manager Plug-ins." Licensees and hardware developers can find more information about developing and installing plug-ins in the book Network Driver Design Guide in the Palm OS Platform Development Kit (PDK).
The Connection Manager controls the communications plug-ins, requesting them to display configuration dialogs to the user, make connections, and terminate connections.
The Connection Manager provides a user interface framework that invokes configuration dialogs supplied by plug-ins, handles transitions between forms, allows editing of configurations and profiles, and includes progress indicators and error display.
The main functions of the Connection Manager include:
- Managing communications plug-ins, which provide specific communications facilities and protocols to the Palm OS
- Managing communications profiles, a kind of communications stack that links together various plug-ins to provide a complete communications path between an application and a remote service
- Establishing connections by using profiles
The Connection Manager only manages connections and does not send or receive data. You must use APIs provided by the plug-ins or the system, such as the STDIO API, to send and receive data once a connection is established.
Terminology
This section defines terms important to understanding the Connection Manager.
- availability
- The Connection Manager determines the availability of a profile by querying each plug-in in the profile. If all plug-ins are available then the profile is available. Availability can change depending on system configuration and external circumstances. For example, a Bluetooth connection may be unavailable if there are no other Bluetooth devices within range.
- communications component
- A piece of code involved in a communications stack. It can implement a protocol or offer services like compression and encryption. A Connection Manager plug-in can represent one or more communications components, and a communications component can be associated with multiple plug-ins.
- Connection Manager database
- A database that stores records that reference plug-ins, interfaces, and connection profiles. All configuration information is stored in this database.
- Connection Manager server
- Most of the Connection Manager code runs in the Connection Manager server, a thread that runs in the system process, along with the plug-ins. The Connection Manager library transparently communicates with the server to accomplish operations requested by API calls.
- connection type
- The protocol used by the top-level component in a profile is the connection type of the profile.
- edge
- A hierarchical relationship between two components, where one component requires another lower-level one to make a connection. A component can have multiple edges to other components if there are multiple options available. The search algorithm uses edges to find related nodes.
- graph
- The hierarchical arrangement of nodes (plug-ins or interfaces) from the connection database that describes all the components that can be used for a particular connection type. It may contain multiple paths, each potentially used for a different profile.
- interface
- A graph node that is an abstraction of plug-ins with similar interfaces. An interface node has no associated code module or user interface components; it is simply an object in the Connection Manager database that relates to other plug-ins.
- macro profile
- A special profile that is used as a macro reference in other profiles. Macro profile names must begin with the special character
kCncMacroSpecialChar
, which is the open curly brace "{". An example of a macro profile is:{MyMacro}="IPIF/ILL"
. The reference, {MyMacro} in this example, can be used in another profile and is expanded to its defined value. Macro profiles are not attached to a communications component. - node
- A plug-in or interface in the Connection Manager graph, with its associated configuration parameters.
- object
- A connection profile, plug-in, or interface. A plug-in object doesn't contain the plug-in, but simply references it.
- path:
- A sequence of consecutive edges in the graph.
- plug-in
- A Connection Manager plug-in is a piece of code that is responsible for configuring and connecting one or more communications components that implement one or more protocols. A plug-in also contains the user interface parts that are necessary to configure its components.
- profile
- An object that defines an ordering of plug-ins and configuration settings of each referenced plug-in. It is typically stored in the Connection Manager database, but can also be private to an application. A profile has a string equivalent (see profile string).
- profile string
- A string equivalent of a connection profile. It's a list of plug-in names, with some values for their configuration parameters.
- record
- A connection profile stored in the Connection Manager database.
- session
- A communication session between the Connection Manager library and the Connection Manager server. A session is automatically opened when calling any Connection Manager functions that need a session. A session is automatically closed when the application that opened it exits. A session identifier can be used to poll a connection.
- subprofile
- A profile that is referenced by another profile. A subprofile is just a normal profile that is called a subprofile when it is referenced by another profile.
- template
- A special profile which can be copied to create a new profile.
- usability
- The user determines the usability of a profile by checking it in a list of profiles for a connection type. Only the checked profiles in the list are usable. When an automatic connection of that type is requested, the Connection Manager considers only usable profiles.
Connection Profiles
A connection profile is an object that defines a sequence of plug-in and interface nodes from the Connection Manager graph that forms a complete path from a topmost component to a lower-level component that can establish a physical connection. For example, a profile might consist of these ordered components: TCP/IP, PPP, Dialer. This means that the desired protocol, TCP/IP, requires the use of the PPP component, which in turn requires the use of the Dialer component, which establishes a modem connection.
When making a connection, the application generally interacts only with the topmost component, which defines the connection type—TCP/IP, in this example. The application doesn't need to know about the lower-level connections.
Profiles can be created by the user via the Connection application, programmatically, or by software installation. The Connection Manager also allows modification and management of existing profiles via the Connection application or programmatically. An application can also create and manipulate private connection profiles that are visible only to itself (see "Profile Strings").
The Connection Manager database stores records that reference plug-ins, interfaces, and profiles.
A connection profile ID is a unique uint32_t
value that represents a stored connection profile. This is the typical way to reference stored profiles. Other objects stored in the Connection Manager database, such as plug-ins and interfaces, also have unique IDs.
A connection profile has a priority that is used to rank the profile in a list of profiles that have the same connection type. The highest priority profile of a type (such as TCP/IP profiles) is returned first from searches, and profiles are listed from highest to lowest priority in the list of profiles with the same connection type.
Connection profiles also have an availability. The availability indicates if the profile can be connected at the current time (which is not always possible to determine). For example, a Bluetooth plug-in might be able to detect if the device is within range of a Bluetooth access point, and would set this field accordingly.
The Connection Manager features a fallback mechanism that attempts to make a connection using alternate profiles of the same connection type if the highest priority profile has an unavailable status. Profiles of the same connection type are tried in highest to lowest priority order, and only those that have a status of available are used; or, if the availability of a profile is unknown, it is tried. The user can configure the fallback mechanism via the Connection application.
The following subsections contain more details on profiles:
- Subprofiles
- Profile Configuration
- Automatic and Manual Mode Profiles
- Profile Strings
- Macro Profiles
- Templates
Subprofiles
A profile can contain references to other connection profiles, called subprofiles because they are referenced from another profile. When the profile is needed for connection or other purposes, the references are automatically expanded to the full plug-in or interface sequence that they represent.
For example, you might have a TCP/IP profile where the IP/PPP part of the profile is always the same and the dialing part changes as the user travels to different countries. You could make this change by inserting a reference to a subprofile that contains the correct dialing configuration.
You can expand and compress such subprofiles referenced within a profile. To expand all subprofiles within a profile, use CncProfileUngroup()
. To recompress a profile that was previously expanded, use CncProfileRegroupSubmit()
. This function resubmits each subprofile to the Connection Manager database as a separate profile and replaces each one in the main profile with a reference.
You can also substitute one subprofile for another in a locked expanded profile by calling CncSubProfileAssign()
.
Profile Configuration
Each node in a profile has an associated property list that contains configuration parameters for its component. Because the configuration parameters are stored in the profiles, different profiles that use the same component can specify different parameter values for it.
To be usable, profiles must be configured; that is, each plug-in in the profile must have at least those parameters set that are needed to make a connection. There are three agents that can assign parameters to a node ( that is, set parameters in the property list of the plug-in):
- Installation code: The plug-in installation code can define default parameters or find parameter values in the property lists of other nodes during plug-in installation.
- User: The user can set parameters when creating or changing a profile via the Connection application; or the user can be asked to supply missing parameters by the plug-in during a connection attempt.
- Application: An application can programmatically set plug-in parameters.
The Connection application serves as a central mechanism for managing and configuring all connections on the handheld. It manages choosing the node path to form complete profiles. And it provides a user interface framework that can display dialogs supplied by plug-ins, for the user to supply configuration parameters or choose among options.
Note that the Connection application itself is not visible in the Launcher. The Internet, Phone, and other communication configuration applications just sublaunch the Connection application, which shows only the relevant profiles.
Automatic and Manual Mode Profiles
Profiles can be automatic or manual. In a list of automatic profiles for a particular connection type, the Connection Manager selects a profile to use depending on its usability, availability, and priority. For example, the Internet panel lists several network profiles in priority order. If the user selects Choose Profile Automatically, the system selects the highest priority profile that is usable and available when a network connection is requested.
The user determines usability by checking the boxes next to the profiles that are usable, as shown in the following figure. The Connection Manager determines availability internally, by querying each plug-in in a profile to see if it is available. The red symbols in the figure below indicate unavailable profiles. The circle with a slash is a generic "unavailable" symbol (for profiles that don't supply their own), and the antenna with red X is the unavailable symbol for phone profiles.

If the user selects Choose Profile Manually, the user must choose a specific profile from the list; this profile is always used when a connection of that type is requested. If the selected profile is not available at the time a connection is requested, then no connection is made.

What makes a profile automatic or manual is a flag (kCncManualModeOption
in CncInfoType
.options) that is set in the first plug-in in the profile. This is the plug-in to which the profile is attached. Because all profiles of the same connection type have the same first plug-in, the profiles in a particular list are either all automatic or all manual.
Profile Strings
A connection profile object can be represented textually by a connection profile string that lists the node names and their properties.
An application can have a private profile, not stored in the Connection Manager database or visible to other applications, by saving a profile string.
The general format of a profile string is:
"node1:properties/node2:properties/..."
where node1 and node2 are plug-in and interface nodes in the Connection Manager graph and properties are property lists associated with the nodes. Each node is separated from the next by a forward slash (/).
Property lists are pairs of parameter names and values separated by commas. Note the following when writing parameters:
- Binary parameters are encoded using a textual hexadecimal representation enclosed in square brackets (for example, [645a3100]). (The usual 0x prefix is not used.)
- String parameters are enclosed in single quotes.
- Special characters in the names or values of parameters, as well as the equal sign and quote symbols, must be represented with quoted-printable notation. Quoted-printable notation consists of an equal sign followed by a two digit hexadecimal representation of the character's value (for example, =3D). For details on quoted-printable notation, refer to RFC 2045 at:
http://www.ietf.org/rfc/rfc2045.txt - Integers begin with a digit.
- Hexadecimal numbers begin with 0x (for example, 0x4a).
Here is an example of creating a string profile and then storing it in a profile object:
sprintf(profile, "SerialMgr:name='PortCOM1',crea=0x%08X/Serial:Baud=%d,FCtl=0x%X,Bits=0x%X", 'com1', B9600, CRTSCTS, CS8); profileId = CncProfileDecode("SerialMgrPort1Profile", profile);
Macro Profiles
A macro profile is a special type of subprofile whose name begins with the special character kCncMacroSpecialChar
, which is the open curly brace "{". For example, {MyMacro} could be the name of a macro profile that is defined as follows:
{MyMacro} = "IPIF/ILL"
When it appears in a profile, a macro name is automatically expanded to its full definition on connection, control, and search requests. You can also expand the macros in a profile by calling CncProfileUngroup()
.
Say there is a profile defined as follows:
MyProfile ="{MyMacro}/DLE"
When the profile is expanded, it becomes "IPIF/ILL/DLE"
, using the definition of MyMacro above.
Macro profiles are not attached to any plug-in or interface. They are used as references in profiles or templates.
The two special macros {REPLACE} and {USING} are used in template profiles created by plug-in developers. Normal profiles don't need to use these.
Templates
Templates are special profiles used when creating a new profile. When creating a new profile, the user typically chooses a template that is copied to a real profile.
A template contains the properties and default settings applicable to the connection type. These can then be customized by the user in the Connection application.
Template profiles are generally created only by plug-in developers.
Link Objects
Link objects are used to associate different names to the same profile. They act like symbolic links or shortcuts; they reference another object and when they are found in a search, the real profile they point to is returned.
This is useful if you create default profiles with internationalized names but also want such profiles to be referenced by others with a well known, unchanging name. For example a link named "RS232 at 115200bps" can point to the profile named "RS232 ā 115200bps" in French. If a search finds the profile ID of "RS232 at 115200bps," the profile ID of "RS232 ā 115200bps" will be returned.
Security Considerations
The Connection Manager addresses security in a number of ways. The Connection Manager server, which does all the actual work, runs in the system process, separate from the application process where applications run. Access to the system process is restricted, though plug-ins, which also run in the system process, do have access so they can read and send passwords to establish a connection, for example.
Connection passwords, along with other sensitive parameters, can be designated as write-only by plug-ins. Such passwords and parameters cannot be read by applications. Also, the user interface for a plug-in in the Connection application can give the user the choice not to store the password (they must enter it each time).
Plug-in installation is protected by the Security Manager. Plug-in code must be signed to guarantee its authenticity.
Persistent Connections
A persistent connection is a connection that is maintained even when applications switch. For example, an application may open a type of connection that is persistent, then the user may switch to a different application, and the connection is still maintained even though the application that opened it has stopped running.
Persistency is a property of a plug-in, and thus of the profiles attached to that plug-in. All built-in network profiles are persistent. Plug-in developers may define other types of persistent connections.
An application can determine if a persistent network connection exists by checking the kCncIsConnectedOption
flag in the CncInfoType.options
field of a profile, as shown in Listing 1.1.
Listing 1.1 Checking for a network connection
// Returns true if there is a network connection Boolean IsOnline(void) { Boolean isOnline = false; uint32_t profileID; // ID of the network interface status_t err; // Result code CncInfoType* profileList = NULL; // the profiles list int16_t profileCount = 0; // the profiles count int16_t index; // get the updated profile list // kCncNetOutgoingInterface is defined in NetCnc.h (TCP/IP) profileID = CncObjectGetIndex(kCncNetOutgoingInterface); if (0 == profileID) return false; err = CncObjectFindAll(profileID, kCncFindDefault, &profileCount, &profileList); if (errNone != err || 0 == profileCount) return false; // update online feature for (index = 0; index < profileCount; index++) { if ((profileList[index].options & kCncIsConnectedOption)!= 0) { isOnline = true; break; } } // free the returned list MemPtrFree(profileList); return isOnline; }
An application can also register for the cncNotifyConnectionStateEvent
notification, which is broadcast whenever the connection state of a persistent profile changes (a persistent profile is connected or disconnected on error or on user request, or the availability of the profile changes).
Graph Management
Most application developers won't need to modify the Connection Manager graph. This section is provided as an overview in case it is necessary.
The Connection Manager maintains a graph of connections between all of the installed communication components, which appear as nodes in the graph. This graph is maintained in the Connection Manager database.
The graph represents hierarchical relationships between components, where a higher component requires the use of a component at the next lower level to establish a connection. Figure 1.2 shows a simplified example of such a graph.
Figure 1.2 Connection Manager graph

Nodes in the graph can be plug-ins (boxes in the figure) or interfaces (ovals in the figure).
An interface is a node that is an abstraction of similar plug-ins that it logically groups together. For example, the IrComm and serial plug-ins both provide the same RS-232 interface, so they can be abstracted by a general RS-232 interface node. An interface node has no associated code module or user interface components; it is simply an object in the Connection Manager database that relates to other plug-in objects.
An interface can be used to logically group profiles (which are attached to nodes in the graph; see "Adding a Profile to a Connection Type List.") For example, a developer might use CncInterfaceNew()
to create a top-level telnet interface node just to attach some telnet-specific profiles to.
Typically, interfaces are used by plug-in developers and you probably won't need to create them.
To establish a connection, the system requires a complete path from a top component in the graph, which defines the connection type, to the bottom component of any branch. There may be several different possible paths from the top component to the bottom component of a branch, each forming a possible connection profile. A communications component can be used in more than one profile.
Components can be linked together by creating relationships, called edges, between them. An edge is simply a hierarchical relationship between two components. It means that the "upper" component requires the "lower" component to make a connection. The upper component may have multiple edges to lower components, meaning that there is a choice of which one to use.
The search algorithm also uses edges internally. For example, if an edge exists between the "RS232" and "Serial" nodes, then searching for "RS232/*" returns profiles attached to the "RS232" node as well as profiles attached to the "Serial" node.
The Connection Manager includes functions to create (CncEdgeNew()
) and delete (CncEdgeDelete()
) edges between components, but these are generally unnecessary to use. Edges are typically created or deleted only by plug-in developers.
Using the Connection Manager
The Connection Manager manages all connections at a high level from the Palm Powered™ handheld to external devices.
The Connection Manager is a shared library that the system automatically loads when needed and unloads when not needed. You don't need to do anything to load or initialize the library.
This section explains how to use the Connection Manager in your application. It covers:
- Making a Connection
- Creating a Profile
- Changing a Profile
- Finding Profiles
- Managing Profiles
- Configuring Components
- Invoking a Function in a Profile Plug-In
Many Connection Manager functions operate on profiles, which are identified by a profile ID number. You can obtain the ID of a profile by passing the name of the profile to CncObjectGetIndex()
or by searching for it with CncProfileFindFirst()
, which searches based on name or a partial profile string. Of course, if you create a new profile with CncProfileNew()
or CncProfileDecode()
, then that function returns the profile ID.
Making a Connection
You can make a connection in the following ways:
These methods are discussed in the following sections.
Connecting From a Stored Profile
To make a connection from an existing profile stored in the Connection Manager database, call CncProfileConnect()
. You pass this function the ID of a stored profile and it makes the connection by requesting each plug-in in the profile to establish a connection, starting with the lowest level. Once the topmost plug-in in the profile has successfully completed a connection, this function returns an IOS file descriptor for the connection.
Applications use the file descriptor to identify the connection for reading and writing data, configuring the connection, or closing it. These tasks can be performed by functions in the STDIO library, which provides a uniform, generic, POSIX-like STDIO interface. For more information, refer to Part VI, "IOS STDIO," in Exploring Palm OS: Low-Level Communications.
Normally, the call to CncProfileConnect()
is synchronous, and blocks until the connection is established. You can call this function in asynchronous mode, however, by setting the kCncConnectAsynchronous
flag. In this case, you must call CncConnectReceiveState()
to receive connection progress and termination messages. The calling application may want to use IOSPoll()
on the session file descriptor (returned by CncGetSession()
) to know when to call this function.
Here's an example of how to use IOSPoll()
to poll the file descriptor for a Connection Manager response, and allow normal user interface event processing to continue while polling.
#define kNfds 2 EventType event; struct pollfd fdList[kNfds]; // the fd list int32_t oNfds; // returned count of fds status_t err; CncConnectionStateType state; fdList[0].fd = CncGetOrOpenSession(); // The CM session fd fdList[1].fd = EvtGetEventDescriptor(); // The event queue fd fdList[0].events = POLLIN; // wait for a normal message fdList[1].events = POLLIN; while(1) { // loop and poll err = IOSPoll(fdList, kNfds, -1, &oNfds); if (err != errNone) break; if (fdList[0].revents & POLLIN) { // process connection manager notifications err = CncConnectReceiveState(&state); // check state and exit loop as needed } else if (fdList[1].revents & POLLIN) { // process UI events do { EvtGetEvent(&event, 0); // process events normally } while(EvtEventAvail()); EvtFinishLastEvent(); } }
If you don't have the ID of a profile to connect, you can use the alternative function, CncProfileFindConnect()
. This function searches the stored profiles by name or partial profile string.
The CncProfileConnect()
and CncProfileFindConnect()
functions can have multiple user interface side effects. For example, the user can be prompted to complete or configure the connection profile, if parameter values are missing or the profile does not specify a complete connection path. Some user interface side effects can be allowed or disallowed via the flags
parameter to these functions.
Creating a Profile Dynamically and Connecting
An application may want to use a private profile, not storing it in the Connection Manager database. To do this, the application can privately construct and store a profile string without using any Connection Manager functions. To connect using it, pass the string to CncProfileFindConnect()
. When passed a complete profile string, this function creates a profile object from it and connects using that profile.
Note that calling any connection function can have multiple user interface side effects, as noted in the previous section.
Canceling or Disconnecting a Profile
If you want to cancel the connection process before it is completed, you can call CncProfileDisconnect()
. You can also call this function to disconnect a persistently connected profile.
Creating a Profile
Users generally create profiles through the Connection application. An application can create a profile programmatically as well.
To create a new empty profile, call CncProfileNew()
. To add items such as plug-ins, interfaces, and other profiles to it, call CncProfileInsertItem()
. To submit the changes to the Connection Manager database and unlock the profile, call CncProfileSubmit()
.
You can also create a profile by passing a string to CncProfileDecode()
.
You can create a profile dynamically, when you want to make a connection. For details, see the previous section, "Configuring Components."
If you create a profile but don't submit it to the Connection Manager database, it won't be saved after your application exits. However, it is associated with the client session while your application is running and it will be found by the find functions described in "Finding Profiles."
For information on configuring the individual communications components in the profile, see "Configuring Components."
Changing a Profile
You can change a profile in the following ways:
- Add new components such as plug-ins and interfaces
- Delete components from the profile, or the profile itself
- Launch the configuration application
These tasks are discussed in the following sections.
Adding Components to a Profile
To add components such as plug-ins, interfaces, and other profiles to a profile, call CncProfileInsertItem()
. Adding a component inserts a reference to it into the sequence of components that comprise a profile.
One profile can even be inserted into another as a subprofile; for details, see "Subprofiles."
Changes you make to a profile are not saved until you submit the changes to the Connection Manager database by calling CncProfileSubmit()
.
Deleting Components and Profiles
To delete a plug-in or interface component and its associated parameters from a profile, call CncProfileDeleteItem()
.
Changes you make to a profile are not saved until you submit the changes to the Connection Manager database by calling CncProfileSubmit()
.
To delete a profile from the Connection Manager database, call CncObjectDelete()
. Removing a plug-in or interface object also removes all edges and profiles that use it. Removing a profile also removes profiles that reference it.
Launching the Configuration Application
To allow the user to complete or edit a profile or configure components, you can launch the Connection application by calling CncProfileEdit()
. By setting a flag, you can control what form the application displays on launch. There are several options, such as the form that lists connection types, the form that lists profiles available for a particular connection type, the configuration form, the profile creation form, and the profile deletion form.
Finding Profiles
There may be many different profiles stored in the Connection Manager database. You can always find a profile object from its name by using CncObjectGetIndex()
, but if you don't know its name, you can use the find functions.
There are two ways to find profiles:
- Use
CncObjectFindAll()
to find all profiles that are attached to a particular plug-in or interface. This function returns all found profiles in an array. - Use
CncProfileFindFirst()
to find a profile based on its name or partial profile string, then iterate through other matching profiles withCncProfileFindNext()
. This method is explained in more detail in the following paragraphs.
To begin a search for a profile based on its name or a partial profile string, call CncProfileFindFirst()
. You can pass this function a partial profile string such as "NetOut/*", to find profiles that begin with it. This example finds network profiles. The "/*" characters are a wildcard at the end that signify a partial string. For details about profile strings, see "Profile Strings."
The CncProfileFindFirst()
function returns the first profile that matches the search string and creates a search object that you can query repeatedly by calling CncProfileFindNext()
to return the next matching profile.
Both CncProfileFindFirst()
and CncProfileFindNext()
return locked profiles, so if you don't want to edit the returned profiles, you might want to call CncProfileUnlock()
in the search loop.
It's good practice to call CncProfileFindClose()
to clean up memory when you are done with a search, after you have called CncProfileFindNext()
for the last time. This function frees the memory used for the search object allocated by CncProfileFindFirst()
.
Note that you can also use the CncProfileFindFirst()
function to create a new profile. If you specify a complete profile string for the search string, this function creates and returns the ID of a new profile object. However, the profile is automatically deleted when the Connection Manager session closes, unless you call CncProfileSubmit()
to save it.
If you create a profile but don't submit it to the Connection Manager database, it isn't saved, but it is associated with the client session while your application is running and it will be found by the find functions described in this section. Other applications won't find it, because each application using the Connection Manager server has its own exclusive client session. Only after it is submitted can other applications find it.
Managing Profiles
Profile management involves tasks such as:
- Getting information about profiles and items
- Adding a profile to the list of those available for a particular connection type
- Locking, unlocking, and submitting changes
These tasks are discussed in the following sections.
Getting Information About Profiles and Items
Before you can work with profiles and the communications components in them, you'll need to obtain their IDs, which are unique identifiers assigned to all Connection Manager objects. You can obtain the ID of a profile by passing the name of the profile to CncObjectGetIndex()
or by searching for it with CncProfileFindFirst()
, which searches based on its name or a partial profile string.
Most operations on the items in a profile require the index of the item in the profile, which you can obtain by passing its name to CncProfileGetItemIndex()
. From the index, you can obtain an item's ID by calling CncProfileGetItemId()
.
To determine the number of items in a profile, use CncProfileGetLength()
.
An information structure, CncInfoType
, is associated with each profile and item object, and is stored in the Connection Manager database. This structure contains information such as the object's name, version, type, and for profile objects, the priority and availability. You can use the functions CncObjectGetInfo()
and CncObjectSetInfo()
to get and set the information in this structure.
Adding a Profile to a Connection Type List
On a Palm OS device, users can request connections by type. The type of a connection is identified by the topmost plug-in of its profile. All the profiles that share that topmost plug-in are of the same type. Some of the top-level plug-ins typically include TCP/IP (network), Serial, Bluetooth, and Phone. Each of these connection types might have several associated profiles.
For each connection type, the associated Connection Manager panel lists the various profiles available, so the user can choose which to use. For example, to make a TCP/IP connection, the user might have the choice of profiles that use a dial-up connection to an ISP, a Bluetooth connection to an ISP through a LAN access point, or a GPRS connection through a mobile phone via an infrared link.
Here's an example of a list of possible network connection profiles shown in the Internet panel:

To add a new profile to the list for a particular connection type (called "attaching" a profile), use the function CncProfileAttach()
. For example, calling this function to attach a profile to the TCP/IP plug-in would add it to the list shown above.
The order in which the profile is inserted into the list is determined by its priority (see the priority
field of CncInfoType
) relative to the existing profiles in the list. The list is ordered from highest to lowest priority and determines the order in which profiles are returned by CncProfileFindNext()
when searching for profiles of the same connection type.
You can change the position of a profile in the list by calling CncObjectMoveItem()
. Note that this doesn't change the priority of the profile, however. The priority is used only once —to initially place the profile in the list.
Locking, Unlocking, and Submitting Profiles
Before you can perform most operations on a profile, such as editing it or configuring its components, you must lock the profile. This prevents other threads from trying to modify the profile at the same time. You can lock a profile by calling CncProfileLock()
. (Note that CncProfileUngroup()
also locks a profile.)
If you create a new profile with CncProfileNew()
, the returned profile is automatically locked.
To save the changes when you are done changing a profile, call CncProfileSubmit()
. This function submits the changes to the Connection Manager database and unlocks the profile.
If you want to unlock a profile without saving any changes, call CncProfileUnlock()
.
Locks are counted and if you lock a profile more than once, but only unlock it once, it is still locked.
Locks are cleaned up by the Connection Manager. If your application exits and leaves a profile locked, it will automatically be unlocked.
Configuring Components
The communications components referenced by a profile typically have various parameters that can be set to control some aspect of the communications operation. For example, a TCP/IP plug-in might have parameters that specify the IP address, DNS address, timeout, and so forth.
Values for these parameters are stored in the items that are in a particular profile in the Connection Manager database. You can retrieve the parameter values for an item by calling CncProfileGetParameters()
and set the parameter values by calling CncProfileSetParameters()
. Both of these functions use parameter arrays that you can allocate by calling CncParametersInit()
.
When you are done with the parameter array returned by CncProfileGetParameters()
, call CncParametersFree()
to free the memory used by the array.
To allow the user to complete or edit a profile or configure components, you can launch the Connection application by calling CncProfileEdit()
. By setting a flag, you can control what form the application displays on launch. There are several options, such as the configuration form, profile creation form, partial profile completion form, etc.
Invoking a Function in a Profile Plug-In
An application may want to programmatically invoke a function in a plug-in associated with a profile. You can do this by calling CncObjectControl()
. Using this call, you can send a request to the control function in a single plug-in or in all plug-ins in a profile. The control function in a plug-in accepts a request parameter that tells it what to do, and a parameter block that is associated with the request.
Plug-in developers define the requests that a plug-in can respond to. This feature allows plug-ins to expose proprietary features.
One request that all plug-ins should respond to is the kCncControlAvailability
request, which the Connection application uses to query all plug-ins about their availability.