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
:
- Connection Manager Structures and Types
- Connection Manager Constants
- Connection Manager Notifications
- Connection Manager Functions
For more information on the Connection Manager, see Chapter 1, "Connections."
Connection Manager Structures and Types
This section describes data structures and types used by Connection Manager functions.
CncConnectionStateType Struct
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
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 toCncObjectControl()
. Must be supplied by the caller ofCncObjectControl()
. -
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
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
CncFindOptionsType Typedef
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
andkCncPercentBaseAvailability
(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
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
andkCncPercentBaseAvailability+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 thekCncControlTest
request to the selected profile. -
manualId
- ID of the Internet profile to connect, if
kCncManualModeOption
is set in theoptions
field (read/write field).
See Also
CncObjectFindAll()
, CncObjectGetInfo()
, CncObjectSetInfo()
CncParameterType Struct
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
This section describes constants used by Connection Manager functions.
Connection Options
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
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
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
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 betweenkCncProfileObject
andkCncTemplateObject
. -
#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 betweenkCncProfileObject
andkCncLinkObject
.
Object Types
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
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
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
Connection Manager Notifications
cncNotifyConnectionStateEvent
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
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
CncCloseSession Function
Purpose
Closes the interprocess communication channel session with the Connection Manager server.
Declared In
CncMgr.h
Prototype
void CncCloseSession( void )
Parameters
Returns
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
CncConnectReceiveState Function
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 stateP
→asyncID
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 stateP
→state
is kCncConnectedState
before attempting to send or receive data. This signals that the connection process is finished and the stateP
→fd
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
Purpose
Deletes an edge (a relationship between two nodes) from the Connection Manager graph.
Declared In
CncMgr.h
Prototype
status_t CncEdgeDelete( uint32_tfromId
, uint32_ttoId
)
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
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_tfromId
, uint32_ttoId
)
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 useCncObjectGetIndex()
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
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
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
Purpose
Returns the existing interprocess communication channel session with the Connection Manager server.
Declared In
CncMgr.h
Prototype
int32_t CncGetSession( void )
Parameters
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
CncInterfaceNew Function
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
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
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_tobjectId
, uint32_trequest
, 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
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
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
Purpose
Searches all items associated with an object.
Declared In
CncMgr.h
Prototype
status_t CncObjectFindAll( uint32_tobjectId
, CncFindOptionsTypeoptions
, 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 withMemPtrFree()
. If you don't want the array of items passed back, set this parameter toNULL
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
CncObjectGetIndex Function
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
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
Purpose
Gets information from the database record of a plug-in, interface, or profile.
Declared In
CncMgr.h
Prototype
status_t CncObjectGetInfo( uint32_trecordId
, 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
CncObjectMoveItem Function
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_titemId
, int16_tnewIndexRelative
)
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
Purpose
Sets information in the database record of a plug-in, interface, or profile.
Declared In
CncMgr.h
Prototype
status_t CncObjectSetInfo( uint32_trecordId
, CncInfoType *infoP
, uint32_tflags
)
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
CncParametersFree Function
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
See Also
CncParametersInit Function
Purpose
Initializes a CncParameterType
array.
Declared In
CncMgr.h
Prototype
void CncParametersInit ( CncParameterTypeparameters
[], int32_tn
)
Parameters
-
↔ parameters
- An array of
CncParameterType
structures. -
→ n
- The number of elements to initialize (typically the size of the array).
Returns
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
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_tfromId
, uint32_ttoId
)
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:
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
Purpose
Makes a connection using a stored connection profile.
Declared In
CncMgr.h
Prototype
int32_t CncProfileConnect( uint32_tprofileId
, uint32_tflags
, 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 stateP
→asyncID
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
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_tfrom
, int16_tto
)
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
orto
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
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
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
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_tlockedId
, uint32_titemIndex
)
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
Purpose
Disconnects a persistently connected profile or cancels the connection process.
Declared In
CncMgr.h
Prototype
status_t CncProfileDisconnect( uint32_tprofileId
, uint8_tkind
)
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
CncProfileEdit Function
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
, CncEditModelaunchMode
, CncEditModeenabledModes
, 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
iskCncEditMode
. 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
Purpose
Encodes a profile into an external string representation.
Declared In
CncMgr.h
Prototype
char* CncProfileEncode( uint32_tprofileId
, int16_tindex
)
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
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
Comments
This function releases any internal data structures used by the find algorithm.
CncProfileFindConnect Function
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_tflags
, 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 stateP
→asyncID
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
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
, CncFindOptionsTypeoptions
, 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 callsCncProfileFindClose()
, 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
CncProfileFindNext Function
Purpose
Continues a profile search in the database and current session.
Declared In
CncMgr.h
Prototype
uint32_t CncProfileFindNext( uint32_tsearchId
, 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
CncProfileGetItemId Function
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_tlockedId
, int16_tindex
)
Parameters
-
→ lockedId
- ID of a locked profile. A profile is locked by
CncProfileLock()
orCncProfileNew()
. -
→ 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 Function
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_tlockedId
, int16_t *index
, char *nameStr
)
Parameters
-
→ lockedId
- ID of a locked profile. You can obtain the ID of a profile by calling
CncObjectGetIndex()
orCncProfileFindFirst()
. A profile is locked byCncProfileLock()
orCncProfileNew()
. -
↔ 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
CncProfileGetLength Function
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()
orCncProfileNew()
. You can obtain the ID of a profile by callingCncObjectGetIndex()
orCncProfileFindFirst()
.
Returns
The number of items in the profile, or -1 if lockedId
is not found.
CncProfileGetParameters Function
Returns parameters of an item (plug-in or interface object) in a profile.
Declared In
CncMgr.h
Prototype
status_t CncProfileGetParameters ( uint32_tlockedId
, int16_titemIndex
, int8_tmethod
, CncParameterTypeparameters
[] )
Parameters
-
→ lockedId
- ID of a locked profile. A profile is locked by
CncProfileLock()
orCncProfileNew()
. You can obtain the ID of a profile by callingCncObjectGetIndex()
orCncProfileFindFirst()
. -
→ 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 byCncParametersInit()
. 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
orparameters
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
CncProfileInsertItem Function
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_tlockedId
, int16_t *atIndex
, uint32_titemId
, CncParameterTypeparameters
[] )
Parameters
-
→ lockedId
- ID of a locked profile. A profile is locked by
CncProfileLock()
orCncProfileNew()
. You can obtain the ID of a profile by callingCncObjectGetIndex()
orCncProfileFindFirst()
. -
→ 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 beNULL
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
orparameters
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
Purpose
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
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
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
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
Returns
Returns the following result codes:
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
CncProfileSetParameters Function
Purpose
Sets the parameters of an item (plug-in or interface object) in a profile.
Declared In
CncMgr.h
Prototype
status_t CncProfileSetParameters( uint32_tlockedId
, int16_titemIndex
, CncParameterTypeparameters
[] )
Parameters
-
→ lockedId
- ID of a locked profile. A profile is locked by
CncProfileLock()
orCncProfileNew()
. You can obtain the ID of a profile by callingCncObjectGetIndex()
orCncProfileFindFirst()
. -
→ 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 byCncParametersInit()
. The last item in the parameter array must have the special namekCncParameterTableEnd
. Note that this item name is set automatically when the array is initialized byCncParametersInit()
.
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
orparameters
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
CncProfileSubmit Function
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
Returns
Returns the following result codes:
See Also
CncProfileUngroup Function
Purpose
Locks a profile and expands all subprofiles and macros used in it.
Declared In
CncMgr.h
Prototype
status_t CncProfileUngroup( uint32_tprofileId
, BooleanregroupTags
)
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:
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
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
Returns
Returns the following result codes:
See Also
CncRegisterPluginModule Function
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_tdbType
, uint32_tdbCreator
, uint16_trsrcId
)
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
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_tlockedId
, int16_titemIndex
, uint32_tnewRefId
)
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:
Comments
This function works only if the profile was expanded by a call to CncProfileUngroup()
, where the regroupTags
parameter was set to true.