|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CompatibilityDefined only if Connection Manager Feature Set is present.
Profile Parameter Size Constants
The size constants specify the size of each of the predefined parameters described in "Profile Parameter Constants." The following table lists the parameter name, the size of its value, and the size constant that gives this size. These size constants are suitable for passing to CncProfileSettingGet and CncProfileSettingSet. CompatibilityDefined only if Connection Manager Feature Set is present.
Device Kind Constants
The device kind constants specify the type of connection being made. You specify the type of connection by defining a value for the kCncParamDeviceKind parameter using CncProfileSettingSet. CompatibilityDefined only if Connection Manager Feature Set is present.
Profile Parameter Types
The parameter type constants specify the type of value stored for a parameter in a connection profile. If you define a new parameter using CncDefineParamID, you must use one of these constants to specify the type of data the parameter stores. The macro CncGetParamType can return this information for any parameter in the profile.
CompatibilityDefined only if Connection Manager Feature Set is present.
Connection Manager Functions
CncAddProfile
PurposeAdds a profile to the Connection Manager. PrototypeErr CncAddProfile (Char *name, UInt32 port, UInt32 baud, UInt16 volume, UInt16 handShake, const Char *initString, const Char *resetString, Boolean isModem, Boolean isPulse) Parameters
Result
CommentsAll profiles within the Connection Manager must have a unique name. The Connection Manager tries to append a duplication number to the end of the name if you specify a name that is already taken. There is a maximum limit to the number of profiles that can be maintained by the Connection Manager. If the limit is passed, an error is returned and that profile will not be added. Profiles that do not need certain fields may pass NULL in the place of a value. CompatibilityImplemented only if New Serial Manager Feature Set is present. If Connection Manager Feature Set is present, use CncProfileCreate instead of using this function. CncAddProfile is still supported for backward compatibility. In Palm OS 4.0 and higher, the maximum number of profiles that can be defined has greatly increased. ExampleAddMyProfile() { Char *myConNameP; Err err; myConNameP = MemPtrNew(cncProfileNameSize); StrCopy(myConNameP, "Foobar"); err = CncAddProfile(myConNameP, 'u328', 57600, 0, 0, "AT&FX4", 0, true, false); MemPtrFree(myConNameP); }
|
-> parameterRange | Use kCncParamThirdPartiesRange to specify that this parameter is not defined by the OS. |
-> parameterType | The type of value stored for the parameter. See "Profile Parameter Types" for a list of possible values. |
-> parameterID | A unique value between 0 to 1023. The value must be unique within the profile for which you are defining the parameter. |
If you are using a parameterType of kCncParamSystemFlag, specify a value from 0 to 31 to identify which of the system flag bit is to be set. |
Returns the parameter ID as a UInt16 value.
You use this macro only if you are defining your own connection profile and have a parameter that you need to define within that profile. The parameter ID immediately precedes its parameter value in the Connection Manager profile database. Because of how the database is formatted, the parameter ID must tell the Connection Manager how to interpret the next series of bytes. For this reason, the high order bits of the parameter ID include information about the type of value and whether the value is defined by the system or a third party.
Parameter IDs of this format are only used if 4.0 New Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Removes a profile from the Connection Manager.
Err CncDeleteProfile (const Char *name)
-> name | Pointer to the name of the profile to be deleted. |
errNone | No error. |
cncErrProfileReadOnly | The profile could not be deleted because it is read only. |
cncErrProfileNotFound | The profile could not be found. |
cncErrConDBNotFound | The connection database is missing. |
The profiles that come preinstalled on the unit are read only and cannot be deleted.
Implemented only if New Serial Manager Feature Set is present.
If Connection Manager Feature Set is present, use CncProfileDelete instead of using this function.
Macro that returns the parameter type portion of the parameter ID.
-> parameterID | A UInt16 that contains the parameter ID. |
Returns a UInt16 value where bits 11 through 14 contain one of the values in "Profile Parameter Types" and the other bits are clear.
Parameter IDs of this format are only used if 4.0 New Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Returns the settings for a profile.
Err CncGetProfileInfo (Char *name, UInt32 *port, UInt32 *baud, UInt16 *volume, UInt16 *handShake, Char *initString, Char *resetString, Boolean *isModem, Boolean * isPulse)
-> name | Pointer to the name of the profile to be returned. Passing in NULL causes this function to return the settings for the profile currently selected in the Connection panel. |
<- port | Pointer to the port identifier that the profile uses. |
<- baud | Pointer to the baud rate that has been set for this profile. |
<- volume | Pointer to the volume of the device (applies only to modems). |
<- handShake | Pointer to the flow control setting (hardware handshaking). 0 indicates automatic (on at speeds > 2400 baud), 1 indicates always on, and 2 indicates always off. |
<- initString | Pointer to the initialization string for the device (applies only to modems). |
<- resetString | Pointer to the reset string for the device (applies only to modems). |
<- isModem | Pointer to a Boolean value: true for Modem, false for Direct. |
<- isPulse | Pointer to a Boolean value: true for Pulse dial, false for TouchTone. |
errNone | No error. |
cncErrGetProfileFailed | The get profile operation failed. The profile may or may not be there. |
cncErrProfileNotFound | The profile could not be found |
cncErrConDBNotFound | The connection database is missing. |
One or more of the parameters may be set to NULL if that information is not desired.
Implemented only if New Serial Manager Feature Set is present.
If Connection Manager Feature Set is present, use CncProfileSettingGet with one of the "Profile Parameter Constants" instead of using this function.
{ UInt32 portID, baud; UInt16 openPort; // get port id err = CncGetProfileInfo("Direct Serial", &portID, &baud, 0, 0, 0, 0, 0, 0); if(!err) { // open the port SrmOpen(portID, baud, &openPort); } }
Returns a list of available profiles that are available through the Connection Manager.
Err CncGetProfileList (Char ***nameListPPP, UInt16 *countP)
<- nameListPPP | Pointer to a pointer to a list of profile names. |
<- countP | Pointer to the number of profile names. |
errNone | No error. |
cncErrGetProfileListFailed | The profile list could not be found. |
cncErrConDBNotFound | The connection database is missing. |
Allocation of the list is handled by the Connection Manager; deallocation is the responsibility of the calling application. Appended to the end of the list will be "-Current-", which represents the profile currently selected in the Connection panel.
Implemented only if New Serial Manager Feature Set is present.
//Declared globally Char ** globalProfileList; ListType *listP; UInt16 globalProfileCount; void SetConnectionList() { //Get the list from the Connection Manager err = CncGetProfileList(&globalProfileList, &globalProfileCount); //Set the UI list LstSetListChoices(listP, globalProfileList, globalProfileCount); } void StopApplication() { UInt16 i; //Deallocate the connection list For(i = 0; i < globalProfileCount; i++) MemPtrFree(globalProfileList[ i ]); MemPtrFree(globalProfileList); }
Macro that returns the number uniquely identifying a system flag parameter.
CncGetSystemFlagBitnum (parameterID)
-> parameterID | The UInt16 containing the parameter ID. |
Returns the ID of the system flag parameter, which is a value from 0 to 31.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that returns the portion of the parameter ID that uniquely identifies the parameter.
CncGetTrueParamID (parameterID)
-> parameterID | A UInt16 containing the parameter ID. |
Returns a UInt16 containing just the parameter ID. The high-order bits, which specify the parameter type and address space, are clear.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that specifies whether the parameter value is fixed length or variable length.
CncIsFixedLengthParamType (parameterID)
-> parameterID | A UInt16 containing the parameter ID. |
Returns true if the parameter is a fixed length parameter type such as UInt32, or false if it is a variable length type.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that returns whether the parameter value is a system flag.
CncIsSystemFlags (parameterID)
-> parameterID | The UInt16 containing the parameter ID. |
Returns true if the parameter type is a system flag. Returns false otherwise.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that specifies whether the parameter is in the system range or in the third-party range.
CncIsSystemRange (parameterID)
-> parameterID | A UInt16 containing the parameter ID. |
Returns true if the parameter ID is defined by Palm OS, or false if it is defined by a third party.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that specifies whether the parameter is defined by a third party.
CncIsThirdPartiesRange (parameterID)
-> parameterID | A UInt16 containing the parameter ID. |
Returns true if the parameter is a third-party parameter, or false if it is a system parameter.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Macro that returns whether the parameter value is a variable-length type.
CncIsVariableLengthParamType (parameterID)
-> parameterID | A UInt16 containing the parameter ID. |
Returns true if the parameter is a variable-length string or a buffer or false if it holds a fixed-length type such as an integer.
Parameter IDs of this format are only used if Connection Manager Feature Set is present.
CncProfileSettingSet, CncProfileSettingGet
Closes the Connection Manager profile database.
None. |
errNone | No error. |
kCncErrDBAccessFailed | The database could not be closed or this is a reference counting error. |
Use CncProfileOpenDB and CncProfileCloseDB as an optimization if you make several Connection Manager calls in succession. All Connection Manager calls open the profile database when they begin and close the database when they are finished. The Connection Manager maintains a reference count that tells it whether the database is open. If you call CncProfileOpenDB before making another Connection Manager call, the next call does not open or close the database. This saves your application the overhead of opening and closing the database each time a call is made.
Implemented only if Connection Manager Feature Set is present.
Returns the number of connection profiles currently defined in the Connection Manager profile database.
Err CncProfileCount (UInt16 *profilesCountP)
<- profilesCountP | The number of profiles. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
Implemented only if Connection Manager Feature Set is present.
Adds a profile record to the Connection Manager profile database.
Err CncProfileCreate (CncProfileID *profileIdP)
<- profileIdP | Upon return, the unique ID of the new profile. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
a Data Manager error | The new record could not be created. |
This function creates a new empty record in the Connection Manager profile database. To populate the profile, use CncProfileSettingSet to set parameter values, including the profile name. Use CncDefineParamID if you need to store information unique to your profile.
Implemented only if Connection Manager Feature Set is present.
CncAddProfile, CncProfileDelete
Err CncProfileDelete (CncProfileID profileId)
profileId | The ID of the profile to delete. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened, or the record could not be deleted. |
kCncErrProfileParamNotFound | The database does not contain a profile with the specified ID. |
The profiles that come preinstalled on the unit are read only and cannot be deleted.
Implemented only if Connection Manager Feature Set is present.
CncDeleteProfile, CncProfileCreate
Returns the ID of the currently selected profile in the Connection panel.
Err CncProfileGetCurrent (CncProfileID *profileIdP)
<- profileIdP | The ID of the current profile. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
Implemented only if Connection Manager Feature Set is present.
CncProfileGetIDFromIndex, CncProfileGetIDFromName, CncProfileGetIndex, CncProfileSetCurrent
Returns the profile ID given its index into the Connection Manager profile database.
Err CncProfileGetIDFromIndex (UInt16 index, CncProfileID *profileIdP)
-> index | The index of the Connection Manager profile. |
<- profileIdP | The ID of the Connection Manager profile. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
kCncErrProfileParamNotFound | No profile at that index. |
Implemented only if Connection Manager Feature Set is present.
CncProfileGetIDFromName, CncProfileGetCurrent, CncProfileGetIndex
Returns the profile ID given its name.
Err CncProfileGetIDFromName (const Char *profileNameP, CncProfileID *profileIdP)
-> profileNameP | The name of the profile. The name is displayed in a pop-up list in the Connection panel. If you pass the string "-Current-", this function returns the ID of the current profile. |
<- profileIdP | The profile ID. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
kCncErrProfileParamNotFound | No profile with the specified name. |
Implemented only if Connection Manager Feature Set is present.
CncProfileGetCurrent, CncProfileGetIDFromIndex, CncProfileGetIndex
Returns the index of the profile given its ID.
Err CncProfileGetIndex (CncProfileID profileId, UInt16 *indexP)
-> profileId | The profile ID. |
<- indexP | The index of the profile's record in the Connection Manager profile database. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
kCncErrProfileParamNotFound | No profile with the specified ID. |
Implemented only if Connection Manager Feature Set is present.
Opens the Connection Manager profile database.
None |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
Use CncProfileOpenDB and CncProfileCloseDB as an optimization if you make several Connection Manager calls in succession. All Connection Manager calls open the profile database when they begin and close the database when they are finished. The Connection Manager maintains a reference count that tells it whether the database is open. If you call CncProfileOpenDB before making another Connection Manager call, the next call does not open or close the database. This saves your application the overhead of opening and closing the database each time a call is made.
The Connection Manager profile database is created if it does not exist.
Implemented only if Connection Manager Feature Set is present.
Err CncProfileSetCurrent (CncProfileID profileId)
-> profileId | The ID of the profile to be made current. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
The current profile is the profile that is used for the next network connection attempt.
Implemented only if Connection Manager Feature Set is present.
Obtains a value stored in one of the Connection Manager profiles.
Err CncProfileSettingGet (CncProfileID profileId, UInt16 paramId, void *paramBufferP, UInt16 *ioParamSizeP)
-> profileId | The ID of the profile from which to obtain a parameter value. |
-> paramId | The ID of the parameter to obtain. See "Profile Parameter Constants" for a list of the parameters used in the profiles that come preinstalled on the device. |
<- paramBufferP | A pointer to a buffer into which to write the parameter value. If the parameter stores a variable-sized value, you can determine the necessary size by passing NULL for paramBufferP. Upon return, paramSize contains the required size. |
<-> ioParamSizeP | On input, a pointer to the size of the buffer into which to write the parameter. On output, points to the number of bytes written to paramBufferP. |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
kCncErrProfileGetParamFailed | The Connection Manager failed to obtain the value of the parameter. |
kCncErrProfileBadSystemFlagBitnum | An attempt was made to obtain the value of a system flag that is undefined. |
kCncErrProfileBadParamSize | The paramBufferP buffer is too small. ioParamSizeP contains the correct size for the buffer. |
kCncErrProfileParamNotFound | The specified parameter is not defined in the profile. |
Implemented only if Connection Manager Feature Set is present.
CncProfileSettingSet, CncGetProfileInfo
Sets a parameter value in the specified profile.
Err CncProfileSettingSet (CncProfileID iProfileId, UInt16 paramId, const void *paramBufferP, UInt16 paramSize)
-> iProfileId | The ID of the profile. |
-> paramId | The ID of the parameter. See "Profile Parameter Constants" for a list of the parameters defined in the preinstalled connection profiles. |
-> paramBufferP | A pointer to the value to set for this parameter. |
-> paramSize | The size of the buffer passed in paramBufferP. See "Profile Parameter Size Constants." |
errNone | No error. |
kCncErrDBAccessFailed | The profile database could not be opened. |
kCncErrProfileParamNotFound | No profile with the specified ID. |
kCncErrProfileSetParamFailed | The Connection Manager failed to set the value of the parameter. |
kCncErrProfileBadParamSize | The paramBufferP buffer is too small. Most likely, the passed in size does not allow space for a string parameter's null terminator. |
kCncErrProfileParamNameHasChange | An attempt was made to set the profile name to a name that is already used. The Connection Manager appends a duplication number to the end of the name and returns this error. You should use CncProfileSettingGet to find out the new name. |
Implemented only if Connection Manager Feature Set is present.
CncDefineParamID, CncProfileSettingGet
|