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

3    Connection Manager Reference

High-Level Communications

Exploring Palm OS®

The Connection Manager allows other applications to access, add, modify, and delete connection profiles contained in the Connection Manager database, and to make and terminate connections.

This chapter provides reference material for the Connection Manager API declared in the header file CncMgr.h:

For more information on the Connection Manager, see Chapter 1, "Connections."

Connection Manager Structures and Types ^TOP^

This section describes data structures and types used by Connection Manager functions.

CncConnectionStateType Struct ^TOP^

Purpose

Contains information about the connection state. This structure is returned by the CncConnectReceiveState() function.

Declared In

CncMgr.h

Prototype

typedef struct CncConnectionStateTag {
   int32_t asyncId;
   uint32_t profileId;
   status_t error;
   int32_t fd;
   uint16_t state;
   uint16_t prgResoureId;
   uint32_t prgModuleCreator;
   uint32_t prgModuleType;
   uint16_t prgStringId;
   uint16_t prgIconId;
} CncConnectionStateType;

Fields

asyncId
Asynchronous operation ID used instead of the file descriptor (in the fd field) for asynchronous connection operations. This identifies which asynchronous operation this structure refers to.
profileId
ID of the connected profile.
error
Error returned by a plug-in or the Connection Manager. Possible Connection Manager errors include: cncErrMemory, cncErrInvalidParam, cncErrObjectTableFull, cncErrObjectNotFound, cncErrCommunication, cncErrMandatoryParameterNotFound. For details on these errors, see "Error Codes."
fd
File descriptor of the IOS connection.
state
Indicates the connection state. Possible values include:
#define kCncConnectedState 0
Connected.
#define kCncConnectingState 1
Connecting.
#define kCncDisconnectedState 2
Disconnected.
#define kCncDisconnectingState 3
Disconnecting.
prgResoureId
Resource ID of the code module associated with this connection.
prgModuleCreator
Creator code of the database that contains progress information for this connection.
prgModuleType
Type code of the database that contains progress information for this connection.
prgStringId
ID of the string containing progress status for this connection. This value, along with prgIconId, is useful for an application that wants to connect without using the default progress dialog. The application can use this information to update its own status display.
prgIconId
ID of the icon associated with progress status for this connection.

CncControlType Struct ^TOP^

Purpose

Contains information about an object. This structure is used by the CncObjectControl() function.

Declared In

CncMgr.h

Prototype

typedef struct CncControlTag {
   uint16_t size;
   uint16_t session;
   status_t error;
   uint32_t Id;
   int16_t index;
   int16_t count;
   uint32_t data;
} CncControlType;

Fields

size
Size of the whole data structure passed in the controlP parameter to CncObjectControl(). Must be supplied by the caller of CncObjectControl().
session
Session identifier to use for CncSrv... functions. The Connection Manager supplies this value to plug-ins as they are called.
error
Error returned from the plug-in function call. This value is set by the plug-in.
Id
Object ID of a plug-in or profile. Must be supplied by the caller of CncObjectControl(). If you specify a plug-in, only that plug-in's control function is called. If you specify a profile, the control function for each plug-in in the profile is called.
index
Index of the current plug-in in the profile, or -1 if the Id field specifies a single plug-in. The Connection Manager supplies this value to plug-ins as they are called.
count
Number of plug-ins in the profile, or -1 if the Id field specifies a single plug-in. The Connection Manager supplies this value to plug-ins as they are called.
data
Function-specific data to be passed to the function and/or returned from it.

CncEditMode Typedef ^TOP^

Purpose

Specifies a mode of operation for the Connection application.

Declared In

CncMgr.h

Prototype

typedef uint32_t CncEditMode;

Constants

#define kCncTechnologyMode ((CncEditMode) 1)
Display a list of communications technologies that can be configured. This lists consists of all profiles that begin with the kCncTechnologiesRoot interface.
#define kCncProfileMode ((CncEditMode) 2)
Display a list of profiles associated with a communications technology, for example network connections.
#define kCncNewMode ((CncEditMode) 4)
Display the profile creation form.
#define kCncDeleteMode ((CncEditMode) 8)
Display the profile deletion form.
#define kCncEditMode ((CncEditMode) 16)
Display the configuration form, for setting component parameters. Each plug-in in the profile is displayed in a separate tab so that the user can configure each plug-in that defines a configuration form.
#define kCncFullMode (kCncTechnologyMode | kCncProfileMode | kCncNewMode | kCncDeleteMode | kCncEditMode)
Reserved for future use.
#define kCncPanelMode (kCncProfileMode | kCncNewMode | kCncDeleteMode | kCncEditMode)
Reserved for future use.
#define kCncAppSwitchMode ((CncEditMode) 0x8000)
The configuration application is launched via an application switch; otherwise, the application is sublaunched.
#define kCncNoDoneButtonMode ((CncEditMode) 0x4000)
The configuration application must not display the Done button.

See Also

CncProfileEdit()

CncFindOptionsType Typedef ^TOP^

Purpose

Specifies the kind of object to find. These constants can be ORed.

Declared In

CncMgr.h

Prototype

typedef uint32_t CncFindOptionsType;

Constants

#define kCncFindAllObjects ((CncFindOptionsType) kCncAllObjects)
Find all objects.
#define kCncFindPluginObjects ((CncFindOptionsType) kCncPluginObject)
Find only plug-in objects.
#define kCncFindInterfaceObjects ((CncFindOptionsType) kCncInterfaceObject)
Find only interface objects.
#define kCncFindProfileObjects ((CncFindOptionsType) kCncProfileObject)
Find only profile objects.
#define kCncFindTemplateObjects ((CncFindOptionsType) kCncTemplateObject)
Find only template objects.
#define kCncFindLinkObjects ((CncFindOptionsType) kCncLinkObject)
Find only link objects.
#define kCncFindAvailableOnly ((CncFindOptionsType) 0x100)
Find only objects that have availability different from kCncNotAvailable and kCncPercentBaseAvailability (0%); these are all available objects.
#define kCncFindUsableOnly ((CncFindOptionsType) 0x200)
Find only objects that have the kCncUsableOption flag.
#define kCncFindInvisible ((CncFindOptionsType) 0x400)
Find objects that are both visible (have the kCncVisibleOption flag) and invisible (without the kCncVisibleOption flag). If the kCncFindInvisible flag is not set, then invisible objects are not found.
#define kCncFindDefault (kCncFindProfileObjects)
Find only profile objects, which is the default.
#define kCncFindAllCountMax 128
Maximum count of objects returned by CncObjectFindAll().

See Also

CncObjectFindAll(), CncProfileFindFirst()

CncInfoType Struct ^TOP^

Purpose

Contains information about a Connection Manager object (plug-in, interface, or profile).

Declared In

CncMgr.h

Prototype

typedef struct CncInfoTag {
   char name[kCncMaxNameLength + 1];
   uint32_t objectId;
   uint8_t version;
   uint8_t type;
   uint16_t count;
   uint8_t priority;
   uint8_t availability;
   uint16_t options;
   uint32_t manualId;
} CncInfoType;

Fields

name
Name of the object (read/write field).
objectId
Object unique ID (read-only field).
version
Version of the object (read-only field).
type
Type of the object (read/write field). One of the constants listed in "Object Types."
count
For a profile, the number of plug-ins and interfaces in it; for a plug-in or interface, the number of profiles that include it (read-only field).
priority
Priority number of the profile (read/write field). 0 is the lowest priority. The priority is used only when a profile is first added to a list of similar profiles, to determine where in the list to insert it. Profiles of the same connection type are listed in order from high priority to low priority.
This value is set by the user via the Connection application, or programmatically by CncObjectSetInfo().
availability
Indicates if the profile can connect at this time (read/write field). By default, all profiles have an availability of kCncProfileAvailable. Possible values include:
#define kCncProfileUnknownAvailability 0
Unknown availability. The Connection manager will try to dynamically determine the availability when asked by querying each plug-in in the profile.
#define kCncProfileAvailable 1
Profile can connect.
#define kCncPercentBaseAvailability 100
The profile is available with a defined percentage, as for a phone signal strength for example. A value between kCncPercentBaseAvailability and kCncPercentBaseAvailability+100 represents a percentage of availability between 0 and 100.
#define kCncProfileNotAvailable 255
Profile cannot connect.
options
Flags that set various characteristics of the object. These constants can be ORed together.
#define kCncHasUIOption 0x8000
Plug-in has a user interface form and a form handler.
#define kCncHasConnectOption 0x4000
Plug-in has a connect callback function.
#define kCncHasFriendlyNameOption 0x2000
Plug-in has a friendly name
#define kCncIsConnectedOption 0x1000
Profile is connected.
#define kCncUsableOption 0x0001
Object is usable for obtaining connect information.
#define kCncVisibleOption 0x0002
Object is visible. When this flag is cleared, the object becomes "invisible" to searches and won't be found by the find functions. Generic template profiles that are never connected or searched are typically made invisible; they only appear in the template list to be copied as the basis of a new profile.
#define kCncUnsearchableOption 0x0004
Object is searchable by search operations.
#define kCncReadOnlyOption 0x0008
Object is read-only and cannot be changed.
#define kCncReplaceOnUsingOption 0x0010
Profile must be copied even if it is referenced by a {USING} macro.
#define kCncUndeletableOption 0x0020
Object cannot be deleted.
#define kCncPersistentOption 0x0040
The profiles attached to the plug-in or interface are persistent.
#define kCncManualModeOption 0x0080
For Internet profiles, the Connection Manager uses the ID specified in the manualId field when trying to connect. If this flag is not set, the Connection Manager uses the first available and usable Internet profile. The configuration application changes this option when the user taps the Automatic/Manual buttons in the Internet profiles list.
#define kCncUserCanChangeModeOption 0x0100
User can change the manual/automatic mode for this plug-in or interface. This option is used by the configuration application.
#define kCncTestableOption 0x0200
This plug-in is testable. If a plug-in has this option set, then the Connection application displays a "Test" button in place of the "Go Online" button for profiles attached to this plug-in. Tapping this button causes the Connection application to call CncObjectControl() and to send the kCncControlTest request to the selected profile.
manualId
ID of the Internet profile to connect, if kCncManualModeOption is set in the options field (read/write field).

See Also

CncObjectFindAll(), CncObjectGetInfo(), CncObjectSetInfo()

CncParameterType Struct ^TOP^

Purpose

Contains information about a parameter of a profile item. This structure is used by the CncProfileGetParameters() and CncProfileSetParameters() functions.

Declared In

CncMgr.h

Prototype

typedef struct CncParameterTag {
   uint32_t name;
   uint16_t size;
   uint8_t type;
   uint8_t reserved;
   union {
      int32_t asInteger;
      char *asString;
      uint8_t *asBinary;
   } value;
} CncParameterType;

Fields

name
Parameter name.
size
Size of the parameter value in bytes.
type
Parameter type; one of the constants listed in "Parameter Types".
reserved
Reserved for system use.
value
Parameter value.

Connection Manager Constants ^TOP^

This section describes constants used by Connection Manager functions.

Connection Options ^TOP^

Purpose

Flags that control how a connection is made.

Declared In

CncMgr.h

Constants

#define kCncConnectProgressUI 1
Allows the Connection Manager to display the progress indicator during the connection process.
#define kCncConnectChooserUI 2
Reserved for future use.
#define kCncConnectDisableFallback 4
Disables the automatic fallback mechanism. The fallback mechanism tries to make a connection using the first available and usable profile, and if it fails, the next one is tried, and so on.
#define kCncConnectDisableReconnection 8
Reserved for future use.
#define kCncConnectAsynchronous 16
Causes the function to return immediately without waiting for the connection completion. The caller must call CncConnectReceiveState() to determine connection progress and status.

See Also

CncProfileConnect(), CncProfileFindConnect()

Control Requests ^TOP^

Purpose

Specify the type of request to send to a plug-in via the CncObjectControl() function.

Declared In

CncMgr.h

Constants

#define kCncControlTest 0x00000080
Requests the plug-in to perform a test function. Built-in plug-ins currently don't support such a function.
#define kCncControlUserChange 0x00000081
Notifies the plug-in that a profile it is part of has changed. Some plug-ins may want to do some kind of update in this case. The Connection application sends this request code to all plug-ins in a profile when the profile is changed.
#define kCncControlAvailability 0x00000082
Requests the plug-in to check its availability. The Connection Manager uses this request code to check the availability of plug-ins in a profile. All built-in plug-ins support this request.

Error Codes ^TOP^

Purpose

Error codes returned by Connection Manager functions.

Declared In

CncMgr.h

Constants

cncErrInvalidParam
One or more of the function parameters is invalid.
cncErrOpenFailed
The Connection Manager failed to open a session with the Connection Manager server.
cncErrObjectTableFull
There are too many locked profiles (from all sessions). Unlock some profiles and try again.
cncErrInvalidPluginModule
The specified plug-in module is invalid.
cncErrMemory
Not enough free memory to perform the requested operation.
cncErrNotImplemented
The requested operation is not implemented.
cncErrObjectNotFound
The specified object cannot be found in the database.
cncErrCannotAllocateObject
Cannot allocate a new object in the database.
cncErrObjectFull
Cannot add a new item in the object because the item count limit is reached.
cncErrIndexOutOfRange
The specified index is out of range.
cncErrDatabase
The Connection Manager database cannot be opened or created.
cncErrCommunication
The application cannot communicate with the Connection Manager.
cncErrPluginModuleInitFailed
Failed to initialize the plug-in module.
cncErrInvalidObject
The specified object is invalid.
cncErrObjectAlreadyExists
Cannot create a new object with the same name as an existing object.
cncErrMandatoryParameterNotFound
A parameter required to make a connection is not defined for a plug-in.
cncErrModuleAlreadyLoaded
Internal error.
cncErrNoPluginForm
A plug-in is involved in the configuration application but does not have a configuration form.
cncErrSessionTableFull
There are too many locked profiles (from the current session). Unlock some profiles in the current session and try again.
cncErrExclusiveObject
Tried to lock an object while another client has exclusive access to it.
cncErrObjectInUse
Attempt to delete a locked object.
cncErrAlreadyDisconnecting
Attempt to disconnect a profile while the profile is already in a disconnecting or disconnected mode.
cncErrUndeletableObject
Attempt to delete an object that has the kCncUndeletableOption option flag.
cncErrReadOnlyObject
Attempt to change an object that has the kCncReadOnlyOption option flag.

Object Information Flags ^TOP^

Purpose

Specify which fields in the CncInfoType structure are set by the CncObjectSetInfo() function.

Declared In

CncMgr.h

Constants

#define kCncNameInfoFlag 1
The name field.
#define kCncPriorityInfoFlag 2
The priority field.
#define kCncAvailabilityInfoFlag 4
The availability field.
#define kCncOptionsInfoFlag 8
The options field.
#define kCncOptionsSetInfoFlag 16
Set to 1 (with an OR operation) the bits specified in infoP.options.
#define kCncOptionsClearInfoFlag 32
Set to 0 (with an AND NOT operation) the bits specified in infoP.options.
#define kCncOptionsInvertInfoFlag 64
Invert (with an XOR operation) the bits specified in infoP.options.
#define kCncToggleTemplateInfoFlag 128
Changes a profile that is not a template into a template; or changes a template profile into a regular profile. This flag toggles the setting of the infoP.type field between kCncProfileObject and kCncTemplateObject.
#define kCncManualIdInfoFlag 256
Sets the default profile attached to a top-level plug-in; this profile is then used in manual mode.
#define kCncToggleLinkInfoFlag 512
Changes a profile into a link; or changes a link into a regular profile. This flag toggles the setting of the infoP.type field between kCncProfileObject and kCncLinkObject.

Object Types ^TOP^

Purpose

Specify the type of an object.

Declared In

CncMgr.h

Constants

#define kCncPluginObject 0x01
Plug-in object.
#define kCncInterfaceObject 0x02
Interface object.
#define kCncProfileObject 0x04
Profile object.
#define kCncTemplateObject 0x08
Template object.
#define kCncLinkObject 0x10
Template object.

Parameter Types ^TOP^

Purpose

Specify the type of value stored for a parameter in a connection profile.

Declared In

CncMgr.h

Constants

#define kCncUndefinedParameterType 0
Undefined type. When setting parameters, use this type to remove a parameter from a profile.
#define kCncIntegerParameterType 1
Integer type (int32_t).
#define kCncStringParameterType 2
String type (zero terminated).
#define kCncBinaryParameterType 3
Binary data type.

Profile Move Constants ^TOP^

Purpose

Specify how to move a profile in a list of profiles for a particular connection type.

Declared In

CncMgr.h

Constants

#define kCncMoveUp -1
Move the profile one position closer to the top of the list.
#define kCncMoveDown +1
Move the profile one position lower in the list.
#define kCncMoveAsDefault -128
Move the profile to the top of the list, so it becomes the default profile for the connection type.
#define kCncMoveLast 127
Move the profile to the end of the list.

See Also

CncObjectMoveItem()

Connection Manager Notifications ^TOP^

cncNotifyConnectionStateEvent ^TOP^

Purpose

Broadcast by the Connection Manager 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).

Declared In

NotifyMgr.h

Prototype

#define cncNotifyConnectionStateEvent 'cncc'


Parameters

None.

Comments

This notification carries no data, so notification clients will need to query the persistent profiles they are interested in to update their state information.

Connection Manager Functions ^TOP^

CncCloseSession Function ^TOP^

Purpose

Closes the interprocess communication channel session with the Connection Manager server.

Declared In

CncMgr.h

Prototype

void CncCloseSession(
   void
)

Parameters

None.

Returns

None.

Comments

Generally, you do not need to call this function because the Connection Manager closes the session when your application exits.

You might want to use this function to close a session in order to free the session resources if your application no longer needs to use the Connection Manager, but continues running.

If a session is not open, this function does nothing.

See Also

CncGetOrOpenSession()

CncConnectReceiveState Function ^TOP^

Purpose

Blocks until a connection status message from the Connection Manager server is available and then returns it.

Declared In

CncMgr.h

Prototype

status_t CncConnectReceiveState (
   CncConnectionStateType *stateP
)

Parameters

stateP
Pointer to a CncConnectionStateType structure that contains the current state of the connection.

Returns

Returns errNone if the function was successful or returns an error code if not successful.

Comments

When you call this function to connection check status, make sure that the ID returned in statePasyncID matches the asynchronous ID returned by your connection call. This ensures that you are getting the status of the correct asynchronous operation, in case there are more than one in progress.

After calling this function, wait until statePstate is kCncConnectedState before attempting to send or receive data. This signals that the connection process is finished and the statePfd field is set to the file descriptor of the connection. Other intermediate states can be used to update a custom progress UI.

The calling application may want to use IOSPoll() on the session file descriptor (returned by CncGetSession()) to know when to call this function.

Before calling CncConnectReceiveState(), the application must have previously called CncProfileConnect() or CncProfileFindConnect() in asynchronous mode.

For an example of how to poll using IOSPoll(), see "Connecting From a Stored Profile."

CncEdgeDelete Function ^TOP^

Purpose

Deletes an edge (a relationship between two nodes) from the Connection Manager graph.

Declared In

CncMgr.h

Prototype

status_t CncEdgeDelete(
   uint32_t fromId,
   uint32_t toId
)

Parameters

fromId
Start node of the edge; that is, the ID of a plug-in or interface that defines the start of an edge. You can use CncObjectGetIndex() to obtain an object ID.
toId
End node of the edge; that is, the ID of a plug-in or interface that defines the end of an edge.

Returns

Returns the following result codes:

errNone
No error; the edge is deleted.
cncErrObjectNotFound
The specified start or end nodes do not exist.

CncEdgeNew Function ^TOP^

Purpose

Adds a Connection Manager graph edge (relationship) between two nodes (plug-ins or interfaces) in the Connection Manager database.

Declared In

CncMgr.h

Prototype

status_t CncEdgeNew(
   uint32_t fromId,
   uint32_t toId
)

Parameters

fromId
Start node of the edge; that is, the ID of a plug-in or interface that defines the start of the edge. The start node represents a plug-in or interface that uses the node identified by toId; it's "above" the end node in a communications stack. You can use CncObjectGetIndex() to obtain an object ID.
toId
End node of the edge; that is, the ID of a plug-in or interface that defines the end of the edge, below the node identified by fromId, hierarchicaly.

Returns

Returns the following result codes:

errNone
No error; the edge is created.
cncErrObjectNotFound
The specified start or end nodes do not exist.
cncErrObjectFull
A new edge cannot be added to toId.
cncErrMemory
Cannot allocate memory for the edge.

Comments

Use this function in an application that needs a private interface node to link an interface with one or more nodes of the Connection Manager graph.

CncGetOrOpenSession Function ^TOP^

Purpose

Returns the existing interprocess communication channel session with the Connection Manager server. If a session is not already open, this function opens a new session.

Declared In

CncMgr.h

Prototype

int32_t CncGetOrOpenSession(
   void
)

Parameters

None.

Returns

Returns the file descriptor of the session. A returned value of -1 means that a session could not be opened with the Connection Manager server.

Comments

The session ID is a file descriptor. Use this function if you want to call asynchronous functions and want to use IOSPoll() to wait for Connection Manager server replies.

Generally, you do not need to call this function to open a session because the Connection Manager automatically opens a session when your application makes Connection Manager calls that need a session.

See Also

CncCloseSession(), CncGetSession()

CncGetSession Function ^TOP^

Purpose

Returns the existing interprocess communication channel session with the Connection Manager server.

Declared In

CncMgr.h

Prototype

int32_t CncGetSession(
   void
)

Parameters

None.

Returns

Returns the file descriptor of the session. A returned value of -1 means that a session is not open with the Connection Manager server.

Comments

The session ID is a file descriptor. Use this function if you want to call asynchronous functions and want to use IOSPoll() to wait for Connection Manager server replies. The CncGetOrOpenSession() function is a more convenient way to obtain the session file descriptor.

See Also

CncGetOrOpenSession()

CncInterfaceNew Function ^TOP^

Purpose

Creates an empty interface node and adds it to the Connection Manager database.

Declared In

CncMgr.h

Prototype

status_t CncInterfaceNew(
   const char *nameStr,
   uint32_t *Id
)

Parameters

nameStr
Pointer to the interface name.
Id
Pointer to the interface ID that is created. If the name specified by nameStr already exists, a pointer to that existing object ID is returned.

Returns

Returns the following result codes:

errNone
No error.
cncErrMemory
Memory allocation error.
cncErrCannotAllocateObject
The Connection Manager object table is full.
cncErrObjectAlreadyExists
An object already exists with the name nameStr.

Comments

An application can use this function to create a private interface node in the Connection Manager graph. After calling this function, an application would typically call CncEdgeNew() to create relationships between the interface node and one or more plug-ins.

CncObjectControl Function ^TOP^

Purpose

Calls the control function in a single plug-in or in every plug-in in a profile.

Declared In

CncMgr.h

Prototype

status_t CncObjectControl(
   uint32_t objectId,
   uint32_t request,
   CncControlType *controlP
)

Parameters

objectId
ID of the object you want to control. This can be plug-in or a profile. If a profile is specified, the controlF function is called for each plug-in in the profile.
request
The request code, which is passed to the control function in the plug-in. This code tells the plug-in what to do. Universally defined request codes are listed in "Control Requests." Plug-ins can also define their own request codes.
controlP
Parameters that are passed to the control function; see CncControlType.

Returns

Returns the following result codes:

errNone
No error; the object is deleted.
cncErrInvalidParam
One or more function parameters are invalid.
cncErrObjectTableFull
There are too many locked profiles.
cncErrCannotAllocateObject
A new object cannot be allocated.
cncErrSessionTableFull
The object has too many profiles locked in the current session.

Comments

This function serves as a general mechanism for calling directly into the plug-ins associated with a profile, for control or any other purpose. Each plug-in should define a controlF function that is called when CncObjectControl() is invoked.

The request parameter is designed to pass a request code telling the plug-in what to do. The controlP parameter can contain custom parameters needed for the request.

The controlP parameter can be of a type other than CncControlType, but it must have the same first fields as CncControlType. For example, the structure used for the kCncControlAvailability request is defined as follows:


typedef struct CncControlAvailabilityTag { 
    CncControlType control;  
    uint8_t availability; 
    uint32_t moduleCreator;  
    uint32_t moduleType; } 
    CncControlAvailabilityType; 

A new session to the Connection Manager server is created to handle the requests from this function, to avoid conflicting with the client session.

CncObjectDelete Function ^TOP^

Purpose

Deletes a plug-in, interface, or profile from the Connection Manager database.

Declared In

CncMgr.h

Prototype

status_t CncObjectDelete(
   uint32_t nodeId
)

Parameters

nodeId
ID of the object to delete. After deletion, the ID is no longer valid.

Returns

Returns the following result codes:

errNone
No error; the object is deleted.
cncErrObjectNotFound
The specified object ID does not exist.

Comments

Removing a plug-in or interface also removes all edges and profiles that use it. Removing a profile also removes profiles that reference it.

CncObjectFindAll Function ^TOP^

Purpose

Searches all items associated with an object.

Declared In

CncMgr.h

Prototype

status_t CncObjectFindAll(
   uint32_t objectId,
   CncFindOptionsType options,
   int16_t *countP,
   CncInfoType **infoArrayP
)

Parameters

objectId
ID of the object in which to search associated items. For example, specify a profile ID to search all plug-ins associated with that profile.
options
Specifies the kind of object to search for; see CncFindOptionsType.
countP
Number of items found.
infoArrayP
An array of CncInfoType objects for the found items. When you are done with this array, free it with MemPtrFree(). If you don't want the array of items passed back, set this parameter to NULL on input.

Returns

Returns the following result codes:

errNone
No error; the object is deleted.
cncErrMemory
Not enough memory to allocate the array of returned objects.
cncErrInvalidParam
One or more function parameters are invalid.

Comments

This function can be used to find a set of profiles at once, instead of looping with CncProfileFindFirst(), CncProfileFindNext(), and CncProfileFindClose(). Also, CncObjectFindAll automatically allocates memory that it needs.

This function not only finds profiles in the database but also finds profiles created but not yet submitted in the current session.

Returned objects are unlocked.

Example

To find all plug-ins registered with the Connection Manager, call this function like this:


uint32_t profileID; 
status_t err; 
CncInfoType* profileList = NULL; // the profiles list 
int16_t profileCount = 0; // the profiles count 
profileID = CncObjectGetIndex(kCncPluginsRoot); 
if (0 == profileID) return false; 
err = CncObjectFindAll(profileID, kCncFindPluginObjects,  
                       &profileCount, &profileList); 

To find all Internet connection profiles, use this code:


uint32_t profileID; 
status_t err; 
CncInfoType* profileList = NULL; // the profiles list 
int16_t profileCount = 0; // the profiles count 
// kCncNetOutgoingInterface is defined in NetCnc.h (TCP/IP) 
profileID = CncObjectGetIndex(kCncNetOutgoingInterface); 
if (0 == profileID) return false; 
err = CncObjectFindAll(profileID, kCncFindDefault,  
                       &profileCount, &profileList); 

See Also

CncProfileFindFirst()

CncObjectGetIndex Function ^TOP^

Purpose

Gets the ID of a plug-in, interface, or profile, by name.

Declared In

CncMgr.h

Prototype

uint32_t CncObjectGetIndex(
   const char *nameStr
)

Parameters

nameStr
Pointer to the name of the object to return.

Returns

Returns the ID of the object. If the name is not found, returns 0.

Comments

This function parses all of the Connection Manager database named records until the name is found or all records are examined.

CncObjectGetInfo Function ^TOP^

Purpose

Gets information from the database record of a plug-in, interface, or profile.

Declared In

CncMgr.h

Prototype

status_t CncObjectGetInfo(
   uint32_t recordId,
   CncInfoType *infoP
)

Parameters

recordId
ID of the object to return information about.
infoP
Pointer to a CncInfoType structure.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified object ID does not exist.
cncErrInvalidParam
The infoP pointer is not valid (NULL).

See Also

CncObjectSetInfo()

CncObjectMoveItem Function ^TOP^

Purpose

Changes the order of a profile in the list of profiles attached to a communications component.

Declared In

CncMgr.h

Prototype

status_t CncObjectMoveItem(
   uint32_t itemId,
   int16_t newIndexRelative
)

Parameters

itemId
The ID of the item to move.
newIndexRelative
An offset by which to move the item, such as -1, +3, or one of the Profile Move Constants. Specify a negative number to move the item closer to the top of the list and a positive number to move it lower in the list.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified object ID does not exist.
cncErrInvalidParam
One or more function parameters are invalid.
cncErrMemory
Not enough free memory to perform the operation.
cncErrObjectTableFull
There are too many locked profiles.
cncErrIndexOutOfRange
The value specified for newIndexRelative is out of range.
cncErrSessionTableFull
The object has too many profiles locked in the current session.

Comments

This function can also be used to make a profile the default one in a list by moving it to the top of the list.

This function does not change the priority of a profile, only its order in the list.

CncObjectSetInfo Function ^TOP^

Purpose

Sets information in the database record of a plug-in, interface, or profile.

Declared In

CncMgr.h

Prototype

status_t CncObjectSetInfo(
   uint32_t recordId,
   CncInfoType *infoP,
   uint32_t flags
)

Parameters

recordId
ID of the object to set information about.
infoP
Pointer to CncInfoType structure that contains the information to set.
flags
Flags indicating which fields to set. Specify values from the Object Information Flags.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified object ID does not exist.
cncErrInvalidParam
The infoP pointer is not valid (NULL).

See Also

CncObjectGetInfo()

CncParametersFree Function ^TOP^

Purpose

Frees all binary and string parameters in an array of parameters. Use this function after calling CncProfileGetParameters() to free allocated memory.

Declared In

CncMgr.h

Prototype

void CncParametersFree (
   CncParameterType parameters[]
)

Parameters

parameters
An array of CncParameterType structures.

Returns

None.

See Also

CncParametersInit()

CncParametersInit Function ^TOP^

Purpose

Initializes a CncParameterType array.

Declared In

CncMgr.h

Prototype

void CncParametersInit (
   CncParameterType parameters[],
   int32_t n
)

Parameters

parameters
An array of CncParameterType structures.
n
The number of elements to initialize (typically the size of the array).

Returns

None.

Comments

This function sets the last element in the array of parameters to the constant kCncParameterTableEnd. The last array element is required to have this value when setting parameters, so you should set the value of n to one greater than the number of parameters you want to set.

See Also

CncProfileGetParameters(), CncProfileSetParameters()

CncProfileAttach Function ^TOP^

Purpose

Inserts a profile into the list of profiles attached to a plug-in or interface.

Declared In

CncMgr.h

Prototype

status_t CncProfileAttach(
   uint32_t fromId,
   uint32_t toId
)

Parameters

fromId
ID of the plug-in or interface to which you want to attach the profile.
toId
ID of the profile to attach.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
One of the specified object IDs does not exist.

Comments

A plug-in or interface can have several different profiles attached to it, and these are kept in a list for the plug-in or interface. These are typically the profiles that have that plug-in or interface as the topmost component in their sequence, and this defines their connection type. For example, the TCP/IP plug-in might have three attached profiles; these each have TCP/IP as the topmost component.

The order in which CncProfileAttach() inserts the profile into the list is determined by the profile's priority (see the priority field of CncInfoType) relative to the existing profiles in the list. The list is ordered from highest to lowest priority.

CncProfileConnect Function ^TOP^

Purpose

Makes a connection using a stored connection profile.

Declared In

CncMgr.h

Prototype

int32_t CncProfileConnect(
   uint32_t profileId,
   uint32_t flags,
   status_t *error
)

Parameters

profileId
ID of the connection profile to use to establish a connection.
flags
Flags that control how the connection is made. See "Connection Options."
error
errNone if the connection is successful, or a connection error returned by lower-level communications services.

Returns

If error is errNone, returns the file descriptor of the connection. Or, if called in asynchronous mode, returns the asynchronous operation ID, which uniquely identifies this particular asynchronous operation so that when you call CncConnectReceiveState() to determine the status, you can be sure it's for this operation and not some other.

Comments

This function can be called in asynchronous mode with the kCncConnectAsynchronous flag. In this case, the caller must call CncConnectReceiveState() to get connection progress and termination messages. The caller can use IOSPoll() to poll the Connection Manager session file descriptor in order to know when to call CncConnectReceiveState().

When you call CncConnectReceiveState() to check status, make sure that the ID returned in statePasyncID matches the ID returned by CncProfileConnect(). This ensures that you are getting the status of the correct asynchronous operation, in case there are more than one in progress.

This function can have multiple user interface side effects. For example, the user can be prompted for a password or a progress dialog can be displayed. Some side effects are allowed or disallowed via the flags parameter.

See Also

CncProfileDisconnect(), CncProfileFindConnect()

CncProfileCopy Function ^TOP^

Purpose

Creates a new profile by copying a subset of items from an existing profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileCopy(
   uint32_t *profileId,
   int16_t from,
   int16_t to
)

Parameters

profileId
On input, a pointer to the ID of a profile to copy. On output, the ID of the copy of the profile.
from
The index of the item in the profile at which to begin copying.
to
The index of the last item to copy.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified object ID does not exist.
cncErrInvalidParam
One or more function parameters are invalid.
cncErrMemory
Not enough free memory to perform the operation.
cncErrObjectTableFull
There are too many locked profiles.
cncErrIndexOutOfRange
The value specified for from or to is out of range.
cncErrCannotAllocateObject
Cannot allocate a new object in the database.
cncErrSessionTableFull
There are too many locked profiles (from the current session). Unlock some profiles in the current session and try again.

Comments

Use this function to copy a subset of items from a profile and create a new profile from them. All items beginning with the index from and through (and including) the index to are copied to the new profile.

The newly created copy is locked.

CncProfileDecode Function ^TOP^

Purpose

Decodes a profile string into a new profile and submits it to the Connection Manager database.

Declared In

CncMgr.h

Prototype

uint32_t CncProfileDecode(
   const char *profileName,
   const char *pathStr
)

Parameters

profileName
Pointer to the name of the profile.
pathStr
Pointer to the profile path string.

Returns

The ID of the unlocked profile, or 0 if an error occurs.

Comments

Use this function along with CncProfileEncode() to manipulate string representations of connection profiles.

You can use this function to easily create a new connection profile, such as a private connection profile used by an application.

This function submits the newly created profile to the Connection Manager database and automatically attaches the profile to the first plug-in (or interface) in the profile. That is, the profile is added to the list of profiles available for the connection type that corresponds to the first plug-in. (This function calls CncProfileAttach() internally.)

CncProfileDeleteItem Function ^TOP^

Purpose

Deletes an item (plug-in, interface, or a nested profile) and its parameters from a locked profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileDeleteItem(
   uint32_t lockedId,
   uint32_t itemIndex
)

Parameters

lockedId
ID of a locked profile.
itemIndex
The zero-based index of an item to delete in the profile.

Returns

The ID of the locked profile, or 0 if an error occurs.

Comments

The profile must first be locked with CncProfileLock() or CncProfileNew().

CncProfileDisconnect Function ^TOP^

Purpose

Disconnects a persistently connected profile or cancels the connection process.

Declared In

CncMgr.h

Prototype

status_t CncProfileDisconnect(
   uint32_t profileId,
   uint8_t kind
)

Parameters

profileId
ID of the connection profile to disconnect or cancel.
kind
The reason for the disconnection; this is passed to the plug-in. You can specify the following values:
#define kCncUserCancelled 1
The user canceled the connection being made.
#define kCncSystemCancelled 2
The system canceled the connection being made.
#define kCncUserDisconnected 3
The user disconnected the persistent connection.
#define kCncSystemDisconnected 4
The system disconnected the persistent connection.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The ID specified in profileId cannot be found.
cncErrAlreadyDisconnecting
The connection is already being disconnected.

Comments

The profile must be connected or in the process of connecting, otherwise this function returns cncErrObjectNotFound.

See Also

CncProfileConnect()

CncProfileEdit Function ^TOP^

Purpose

Launches the Connection application and opens the configuration form associated with the first plug-in of a profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileEdit(
   uint32_t *Id,
   CncEditMode launchMode,
   CncEditMode enabledModes,
   CncEditParametersType *params
)

Parameters

Id
ID of the profile to configure; the configuration form associated with the first plug-in in the profile is opened if launchMode is kCncEditMode. The ID can be for a plug-in to create or choose a profile beginning with this plug-in.
launchMode
Identifies the mode in which the Connection application is to open. See the CncEditMode type for valid values.
enabledModes
Reserved for future use.
params
Reserved for future use.

Returns

Returns errNone if the ID parameter is valid and references the selected profile. Do not assume that this ID is the same as the one passed in; the user may have switched to another profile or created a new one.

Comments

If the kCncAppSwitchMode bit is set in launchMode, the Connection application is launched via SysUIAppSwitch(). The current application is first closed, then the Connection application is launched.

If the kCncAppSwitchMode bit is not set, the Connection application is sublaunched via SysAppLaunch() (the Connection application is launched as a subroutine of the current application).

If the kCncNoDoneButtonMode bit is set in launchMode, the Connection application does not display a Done button. If the Done button is shown in the Connection application, tapping it returns to the calling application, in the case of a SysAppLaunch().

CncProfileEncode Function ^TOP^

Purpose

Encodes a profile into an external string representation.

Declared In

CncMgr.h

Prototype

char* CncProfileEncode(
   uint32_t profileId,
   int16_t index
)

Parameters

profileId
ID of the profile to encode.
index
The index of a single plug-in within the profile that you want to encode. If you specify a valid plug-in index, then just the string representation of that plug-in is encoded. Specify -1 to encode the whole profile into a string.

Returns

The external string representation of the profile (or plug-in), or NULL if an error occurs. If non-NULL, you must free this by calling MemPtrFree() when you are done with it.

Comments

Use this function along with CncProfileDecode() to manipulate string representations of connection profiles.

You can use this function to help manage an application's private connection profile.

CncProfileFindClose Function ^TOP^

Purpose

Ends a profile search in the database.

Declared In

CncMgr.h

Prototype

void CncProfileFindClose(
   uint32_t searchId
)

Parameters

searchId
ID of the search, returned by CncProfileFindFirst().

Returns

None.

Comments

This function releases any internal data structures used by the find algorithm.

CncProfileFindConnect Function ^TOP^

Purpose

Finds a profile, or creates a profile dynamically, and makes a connection using it.

Declared In

CncMgr.h

Prototype

int32_t CncProfileFindConnect(
   char *profileStr,
   uint32_t flags,
   uint32_t *profileIdP,
   status_t *error
)

Parameters

profileStr
Pointer to the profile search string (profile name, complete profile string, or partial profile string); for example, "NetOut/*". If you specify a complete profile string, this function creates a new profile from it rather than searching the database.
flags
Flags that control how the connection is made. See "Connection Options."
profileIdP
Returns a pointer to the ID of the found profile, if a search was performed. If you don't need the ID to be returned, you can set this parameter to NULL on input.
error
errNone if the connection is successful, or a connection error returned by lower-level communications services.

Returns

If error is errNone, returns the file descriptor of the connection. Or, if called in asynchronous mode, returns the asynchronous operation ID, which uniquely identifies this particular asynchronous operation so that when you call CncConnectReceiveState() to determine the status, you can be sure it's for this operation and not some other.

Comments

This function internally calls CncProfileFindFirst() to search for or create a profile string. If profileStr is a profile name or partial profile string (with "/*" at the end), then CncProfileFindConnect() finds the first matching profile and makes a connection with it.

If profileStr is a complete profile string (without "/*" at the end) then this function creates a new profile from it and makes a connection from it. The profile is not saved in the Connection Manager database unless you call CncProfileSubmit(); if you don't call CncProfileSubmit(), the profile is automatically deleted when the Connection Manager session closes.

This function can be called in asynchronous mode with the kCncConnectAsynchronous flag. In this case, the caller must call CncConnectReceiveState() to get connection progress and termination messages. The caller can use IOSPoll() to poll the Connection Manager session file descriptor in order to know when to call CncConnectReceiveState().

When you call CncConnectReceiveState() to check status, make sure that the ID returned in statePasyncID matches the ID returned by CncProfileFindConnect(). This ensures that you are getting the status of the correct asynchronous operation, in case there are more than one in progress.

This function can have multiple user interface side effects. For example, the user can be prompted for a password or a progress dialog can be displayed. Some side effects are allowed or disallowed via the flags parameter.

The Connection Manager uses the usability and availability properties of profiles to determine if it can connect one that it finds. It won't try to connect a profile that is not usable or available. However, if the first plug-in of a profile is in manual mode, the Connection Manager attempts to connect the profile identified by CncInfoType.manualId regardless of its usability or availability. Manual mode is indicated for a profile when the CncInfoType.options field of its first plug-in has the kCncManualModeOption flag set. For more information on automatic and manual mode, see "Automatic and Manual Mode Profiles."

An application can use this function to make a connection using a private connection profile that it has stored as a string.

See Also

CncProfileConnect(), CncProfileDisconnect()

CncProfileFindFirst Function ^TOP^

Purpose

Begins a profile search in the database and current session, or creates a new profile.

Declared In

CncMgr.h

Prototype

uint32_t CncProfileFindFirst(
   char *searchStr,
   CncFindOptionsType options,
   uint32_t *searchIdP,
   status_t *errP
)

Parameters

searchStr
Pointer to the search string (profile name, complete profile string, or partial profile string); for example, "NetOut/*". If you specify a complete profile string, this function creates a new profile from it rather than searching the database.
options
Specifies the kind of object to search for; see CncFindOptionsType.
searchIdP
Pointer to the new search ID (used by other search functions). If you specify NULL on input, this indicates you don't want the search ID to be returned. In this case, this function internally calls CncProfileFindClose(), to end the search before returning.
errP
errNone if the operation is successful, or an error code if not successful.

Returns

The ID of the first profile matching the search string, or 0 if no profile is found. The found profile is locked.

Comments

If searchStr is a profile name, this function returns that profile ID and the value of searchIdP is set to 0.

If searchStr is a complete profile string (without "/*" at the end) then this function creates a new profile from it and returns the ID of the newly created profile. The value of searchIdP is set to 0. If you do not call CncProfileSubmit(), the profile is automatically deleted when the Connection Manager session closes.

If searchStr is a partial profile string (with "/*" at the end), this function searches for the first matching profile. The value of searchIdP is set to a non-zero value and references the search. This search ID must be passed to CncProfileFindNext() and CncProfileFindClose(). It's good practice to call CncProfileFindClose() to clean up memory when you are done with the search; it needs to be called only when searchIdP returns a non-zero value.

To find the next profile that matches the search criteria, call CncProfileFindNext(); except if you've specified a NULL value for searchIdP on input, in which case the search is closed and no search ID is returned.

This function also finds profiles created but not yet submitted in the current session.

See Also

CncObjectFindAll()

CncProfileFindNext Function ^TOP^

Purpose

Continues a profile search in the database and current session.

Declared In

CncMgr.h

Prototype

uint32_t CncProfileFindNext(
   uint32_t searchId,
   status_t *errP
)

Parameters

searchId
Search ID returned by CncProfileFindFirst().
errP
errNone if the operation is successful, or an error code if not successful.

Returns

The ID of the next profile matching the search criteria established by CncProfileFindFirst(), or 0 if no more matching profiles are found. The found profile is locked.

Comments

The CncProfileFindFirst() function must be called before using CncProfileFindNext().

It's good practice to call CncProfileFindClose() to clean up memory when you are done with the search, after you have called CncProfileFindNext() for the last time.

This function also finds profiles created but not yet submitted in the current session.

See Also

CncObjectFindAll()

CncProfileGetItemId Function ^TOP^

Purpose

Gets the ID of an item in a profile (a plug-in or interface object) from its index.

Declared In

CncMgr.h

Prototype

uint32_t CncProfileGetItemId(
   uint32_t lockedId,
   int16_t index
)

Parameters

lockedId
ID of a locked profile. A profile is locked by CncProfileLock() or CncProfileNew().
index
Index (zero-based) of the item in the profile.

Returns

The ID of the plug-in or interface object, or 0 if an error occurs.

See Also

CncProfileGetItemIndex()

CncProfileGetItemIndex Function ^TOP^

Purpose

Gets the index of an item in a profile (a plug-in or interface object) from the item name.

Declared In

CncMgr.h

Prototype

status_t CncProfileGetItemIndex(
   uint32_t lockedId,
   int16_t *index,
   char *nameStr
)

Parameters

lockedId
ID of a locked profile. You can obtain the ID of a profile by calling CncObjectGetIndex() or CncProfileFindFirst(). A profile is locked by CncProfileLock() or CncProfileNew().
index
On input, a pointer to the index (zero-based) of the item at which to begin the search. Use 0 to search the whole profile. On output, a pointer to the index (zero-based) of the found item, if no error occurs.
nameStr
Pointer to the name of the item to search for.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified profile ID does not exist.
cncErrInvalidParam
The indexP pointer is not valid.

See Also

CncProfileGetItemId()

CncProfileGetLength Function ^TOP^

Purpose

Returns the number of items (plug-in and interface objects) in a profile.

Declared In

CncMgr.h

Prototype

uint32_t CncProfileGetLength(
   uint32_t lockedId
)

Parameters

lockedId
ID of a locked profile. A profile is locked by CncProfileLock() or CncProfileNew(). You can obtain the ID of a profile by calling CncObjectGetIndex() or CncProfileFindFirst().

Returns

The number of items in the profile, or -1 if lockedId is not found.

CncProfileGetParameters Function ^TOP^

Returns parameters of an item (plug-in or interface object) in a profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileGetParameters (
   uint32_t lockedId,
   int16_t itemIndex,
   int8_t method,
   CncParameterType parameters[]
)

Parameters

lockedId
ID of a locked profile. A profile is locked by CncProfileLock() or CncProfileNew(). You can obtain the ID of a profile by calling CncObjectGetIndex() or CncProfileFindFirst().
itemIndex
Index (zero-based) of an item (plug-in or interface) in the profile.
method
Flags that determine the scope of the parameter search:
kCncGetParametersItemOnly
Only the item is searched.
kCncGetParametersInherited
The item and previous items (above in the hierarchy) are searched. If the parameter appears multiple times, the first value found is returned. The profile is parsed right to left (upwards in the hierarchy).
kCncGetParametersWholeProfile
The whole profile is searched. If the parameter appears multiple times, the first value found is returned. The profile is parsed left to right (downwards in the hierarchy).
kCncGetParametersActive
The profile is searched for dynamic parameters that are available only in the current Connection Manager session when a persistent profile is connected. For example, network plug-ins update a network profile with the assigned IP address. Such dynamic parameters exist in the profile in the Connection Manager session, but are not saved to the profile in the database.
parameters
On input, an array of CncParameterType structures that contain the parameter names and types to get; the array previously should have been initialized by CncParametersInit(). On output, an array of those parameter values.

Returns

Returns the following result codes:

errNone
No error; the parameters structures are updated with the parameter values.
cncErrObjectNotFound
The specified profile ID does not exist.
cncErrInvalidParam
The itemIndex or parameters parameter is invalid.

Comments

After you are done using the parameter array, you should call CncParametersFree() to free the memory.

Example


CncParameterType myParams[3]; 
CncParametersInit(myParams, 3); 
myParams[0].name = 'Fctl'; 
myParams[1].name = 'port'; 
index = 0; 
if (CncProfileGetItemIndex(Id, &index, "rs232") == errNone) 
{ 
  CncProfileGetParameters(Id, index, myParams, 
kCncGetInherited); 
  FlowControl = myParams[0].value.asString; 
  PortNumber = myParams[1].value.asInteger; 
  // Do something else here 
} 
CncParametersFree(myParams); 

See Also

CncProfileSetParameters()

CncProfileInsertItem Function ^TOP^

Inserts an item into a locked profile. Items can be plug-ins, interfaces, or other profiles.

Declared In

CncMgr.h

Prototype

status_t CncProfileInsertItem(
   uint32_t lockedId,
   int16_t *atIndex,
   uint32_t itemId,
   CncParameterType parameters[]
)

Parameters

lockedId
ID of a locked profile. A profile is locked by CncProfileLock() or CncProfileNew(). You can obtain the ID of a profile by calling CncObjectGetIndex() or CncProfileFindFirst().
atIndex
Index of an item in the profile at which to insert the new item. Specify 0 to add the item at the beginning, or kCncInsertAtEndIndex to add the item at the end of the profile.
itemId
ID of the item to insert in the profile.
parameters
An array of CncParameterType structures that contain parameters associated with the item being inserted. Can be NULL if there are no parameters.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified profile ID does not exist.
cncErrInvalidParam
The itemID or parameters parameter is invalid.

Comments

To submit the changes to the Connection Manager database and unlock the profile, call CncProfileSubmit().

If you pass a parameters array to this function, note that the array is not freed by this function. After you are done using the array, you should call CncParametersFree() to free the memory.

CncProfileLock Function ^TOP^

Purpose

Locks a stored profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileLock(
   uint32_t Id
)

Parameters

Id
ID of a profile to lock. You can obtain the ID of a profile by calling CncObjectGetIndex().

Returns

Returns the following result codes:

errNone
No error; the profile is locked.
cncErrObjectNotFound
The specified profile ID does not exist.

Comments

Use this function to lock a profile before editing it. To submit the changes to the Connection Manager database and unlock the profile, call CncProfileSubmit(). To only unlock the profile, call CncProfileUnlock().

CncProfileNew Function ^TOP^

Purpose

Creates a new empty, locked profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileNew(
   char *profileName,
   uint32_t *lockedId
)

Parameters

profileName
Pointer to the user-visible name of the profile; for example, "My Fast Internet Connection".
lockedId
Pointer to the ID of the newly created profile. If the name specified by profileName already exists, a pointer to that existing object ID is returned.

Returns

Returns the following result codes:

errNone
No error; the lockedId parameter is set to the ID of the newly created profile.
cncErrMemory
There is not enough memory available to create the new object.
cncErrCannotAllocateObject
The Connection Manager object table is full.
cncErrObjectAlreadyExists
An object already exists with the name profileName.

Comments

An application can use this function to create a new empty profile. To add items, call CncProfileInsertItem(). To submit the changes to the Connection Manager database and unlock the profile, call CncProfileSubmit(). To only unlock the profile, call CncProfileUnlock().

CncProfileRegroupSubmit Function ^TOP^

Purpose

Resubmits to the Connection Manager database all the subprofiles within an expanded profile as separate profiles. The main profile is recompressed by replacing all the subprofiles with references.

Declared In

CncMgr.h

Prototype

status_t CncProfileRegroupSubmit(
   uint32_t lockedId
)

Parameters

lockedId
ID of a locked, expanded profile to recompress.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified profile ID is not found.

Comments

This function works only if the profile was expanded by a call to CncProfileUngroup(), where the regroupTags parameter was set to true.

All individual subprofiles that exist in the main profile are saved in the Connection Manager database as separate profiles and are unlocked. The main profile is recompressed, submitted to the database, and unlocked.

If there are no subprofiles in the specified profile, then this function has the same effect as CncProfileSubmit().

See Also

CncSubProfileAssign()

CncProfileSetParameters Function ^TOP^

Purpose

Sets the parameters of an item (plug-in or interface object) in a profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileSetParameters(
   uint32_t lockedId,
   int16_t itemIndex,
   CncParameterType parameters[]
)

Parameters

lockedId
ID of a locked profile. A profile is locked by CncProfileLock() or CncProfileNew(). You can obtain the ID of a profile by calling CncObjectGetIndex() or CncProfileFindFirst().
itemIndex
Index (zero-based) of an item in the profile.
parameters
Array of CncParameterType structures that contain the parameters to set; the array previously should have been initialized by CncParametersInit(). The last item in the parameter array must have the special name kCncParameterTableEnd. Note that this item name is set automatically when the array is initialized by CncParametersInit().

Returns

Returns the following result codes:

errNone
No error; the parameters structures are updated with the parameter values.
cncErrObjectNotFound
The specified profile ID does not exist.
cncErrInvalidParam
The itemIndex or parameters parameter is invalid.

Comments

To remove a parameter from a profile, use the type kCncUndefinedParameterType.

To submit the changes to the Connection Manager database and unlock the profile, call CncProfileSubmit().

Example


CncParameterType myParams[4]; 
char* myName = "SomeName"; 
 
CncParametersInit(myParams, 4); 
myParams[0].name = 'uart'; 
myParams[0].type = kCncIntegerParameterType; // set an int 
myParams[0].value.asInteger = 0; 
myParams[1].name = 'DevN'; 
myParams[1].type = kCncStringParameterType; // set a string 
myParams[1].value.asString = myName; 
myParams[2].name = 'baud'; 
myParams[2].type = kCncUndefinedParameterType; // remove this 
CncProfileSetParameters(Id, 1, myParams); 

See Also

CncProfileGetParameters()

CncProfileSubmit Function ^TOP^

Purpose

Submits a changed profile to the Connection Manager database and unlocks the profile.

Declared In

CncMgr.h

Prototype

status_t CncProfileSubmit(
   uint32_t lockedId
)

Parameters

lockedId
ID of a profile to submit and unlock.

Returns

Returns the following result codes:

errNone
No error.
cncErrInvalidParam
The specified profile ID is not a locked profile.

See Also

CncProfileUnlock()

CncProfileUngroup Function ^TOP^

Purpose

Locks a profile and expands all subprofiles and macros used in it.

Declared In

CncMgr.h

Prototype

status_t CncProfileUngroup(
   uint32_t profileId,
   Boolean regroupTags
)

Parameters

profileId
ID of a profile to expand.
regroupTags
Specify true to allow all macros to be compressing back into macro form later. This option inserts BEGIN and END tags around each expanded portion, to allow future recompression.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified profile ID is not found.

Comments

Each subprofile and macro is expanded by copying the subprofile or macro definition into the profile in place of its reference.

If there are no subprofiles or macros in the specified profile, then this function has the same effect as CncProfileLock().

See Also

CncProfileRegroupSubmit(), CncSubProfileAssign()

CncProfileUnlock Function ^TOP^

Purpose

Unlocks a locked profile without submitting changes to the Connection Manager database.

Declared In

CncMgr.h

Prototype

status_t CncProfileUnlock(
   uint32_t lockedId
)

Parameters

lockedId
ID of a profile to unlock.

Returns

Returns the following result codes:

errNone
No error.
cncErrInvalidParam
The specified profile ID is not a locked profile.

See Also

CncProfileSubmit()

CncRegisterPluginModule Function ^TOP^

Purpose

Registers a code module that contains one or more plug-ins with the Connection Manager and adds the description to the database.

Declared In

CncMgr.h

Prototype

status_t CncRegisterPluginModule(
   uint32_t dbType,
   uint32_t dbCreator,
   uint16_t rsrcId
)

Parameters

dbType
Type of the code module.
dbCreator
Creator ID of the code module.
rsrcId
Code resource ID of the code module.

Returns

The ID of the newly added plug-in code module, or 0 if an error occurs. If the code module is already registered, this function returns the ID of the registered module without affecting the Connection Manager database.

Comments

This function does not need a session with the Connection Manager. A module can use this function at boot time, before the Connection Manager thread is running.

The referenced code module is sublaunched twice. The code must respond to the sysCncPluginLaunchCmdGetPlugins launch code to pass back the plug-in definitions, and then to sysCncPluginLaunchCmdRegister if more initialization is needed after the plug-ins are registered with the Connection Manager. For more information on these launch commands, refer to Exploring Palm OS: Programming Basics.

CncSubProfileAssign Function ^TOP^

Purpose

Changes a subprofile in an expanded profile to a different subprofile, which is also expanded within the main profile.

Declared In

CncMgr.h

Prototype

status_t CncSubProfileAssign(
   uint32_t lockedId,
   int16_t itemIndex,
   uint32_t newRefId
)

Parameters

lockedId
ID of a locked, expanded profile within which to change a subprofile.
itemIndex
Index of the subprofile to change. The index refers to the index of the BEGIN tag that marks the subprofile. The first BEGIN block within a profile has an index of 0.
newRefId
ID of a profile to substitute as a subprofile into the main profile in place of the subprofile identified by itemIndex.

Returns

Returns the following result codes:

errNone
No error.
cncErrObjectNotFound
The specified profile ID is not found.

Comments

This function works only if the profile was expanded by a call to CncProfileUngroup(), where the regroupTags parameter was set to true.

See Also

CncProfileRegroupSubmit()