This chapter documents the Connection Manager plug-ins that are commonly built into the Palm OS®. If you need to construct custom Connection Manager profiles, you will need to know what plug-ins are available and what their parameters are. This chapter describes the following plug-ins and groups of plug-ins:
A particular Palm OS device may not have all of the Connection Manager plug-ins described here, or may have additional plug-ins, depending on the communication hardware installed in the system.
For information about setting and getting plug-in parameters, see "Configuring Components." You can also work with plug-in parameters in profile strings, and this is described in "Profile Strings."
Note that plug-in development is not covered in the SDK. Licensees and hardware developers can find more information about developing and installing plug-ins in the book Network Driver Design Guide in the Palm OS Platform Development Kit (PDK).
Network Plug-ins ^TOP^
All network profiles start with the NetOut interface. This interface serves as the top-level network component in the system. It is not a plug-in, but rather an interface, below which all other plug-ins in the TCP/IP stack reside.
Below the NetOut interface, the TCP/IP stack includes the following plug-ins:
Some parameters of the network plug-ins can reside in more than one plug-in in the network stack.
Some parameters of the network plug-ins are dynamic; that is, they are set by the plug-in after the connection is active.
IPIF Plug-in ^TOP^
The IPIF (IP Interface) plug-in resides in the layer below the NetOut interface in the TCP/IP stack. The IPIF plug-in manages the configuration of IP networking interfaces and other associated configuration information such as network routes, domain name resolver configuration entries, etc. It also controls DHCP when automatic configuration is enabled.
The IPIF plug-in has a user interface that is accessed via the TCP/IP tab in the Connection application for Internet profiles. This tab allows the user to set certain configuration parameters such as automatic (IP address is supplied by DHCP) or manual mode (IP address is supplied by the user), DNS servers, and DNS suffixes.
The complete list of parameters that you can set or get for the IPIF plug-in is shown in Table 2.1.
Table 2.1 IPIF plug-in parameters
Parameter
|
Type
|
Description
|
'LoIP'
|
string
|
Local IP address, in dotted notation. If this parameter is missing, automatic mode is assumed and the DHCP client is started for this connection. This value is set by the IP Address field in the TCP/IP tab if Manual mode is chosen.
|
'ReIP'
|
string
|
Remote IP address for PPP links, in dotted notation. Set only in manual mode. If this parameter is present, a PPP link is assumed and a default route is added, using this address as a default gateway.
|
'_MTU'
|
unsigned integer
|
Maximum transmit unit in bytes. Defaults to the value provided by the lower-level layer (DLPI or PPP).
|
'NetM'
|
string
|
Subnet mask; formatted as a dotted IP address. Set only in manual mode; in automatic mode it is computed automatically. This value is set by the Subnet Mask field in the TCP/IP tab if Manual mode is chosen.
|
'Brod'
|
string
|
Broadcast address. Set only in manual mode; in automatic mode, it is computed automatically.
|
'IFFS'
|
unsigned integer
|
Interface bits to set, which override the default IP configuration set by the SIOCSIFFLAGS ioctl command. Set only in manual mode.
|
'IFFC'
|
unsigned integer
|
Interface bits to clear, which override the default IP configuration set by the SIOCSIFFLAGS ioctl command. Set only in manual mode.
|
'IFId'
|
unsigned integer
|
Interface ID for use with the 'LLNa' parameter to build the interface name.
|
'LLNA'
|
string
|
Link name for use with the 'IFId' parameter to build the interface name.
|
'Mtic'
|
unsigned integer
|
Interface metric (defaults to 1 if not available). A metric is a value that is assigned to an IP route for a particular network interface that identifies the cost that is associated with using that route. For example, the metric can be valued in terms of link speed, hop count, or time delay. Higher metrics have the effect of making a route less favorable.
|
'DNSs'
|
string
|
List of DNS servers formatted as a list of dotted IP addresses, separated by spaces. This value is set by the DNS Servers form in the TCP/IP tab.
|
'GWys'
|
string
|
List of default gateways formatted as a list of dotted IP addresses, separated by spaces. This value is set by the Gateway field in the TCP/IP tab if Manual mode is chosen.
|
'Doms'
|
string
|
List of DNS domain suffixes separated by spaces. This value is set by the DNS Suffixes form in the TCP/IP tab.
|
ILL Plug-in ^TOP^
The ILL (IP Link Layer) plug-in implements a Data Link Provider Interface (DLPI). It resides below the IPIF plug-in in the TCP/IP stack. Those interested in the DLPI specification can find it at:
http://www.opengroup.org/onlinepubs/9638599/toc.htm
The ILL plug-in has no user configurable parameters and thus has no user interface.
The complete list of parameters that you can set or get for the ILL plug-in is shown in Table 2.2.
Table 2.2 ILL plug-in parameters
Parameter
|
Type
|
Description
|
'DDev'
|
string
|
DLPI device name.
|
'DPPA'
|
unsigned integer
|
DLPI physical point of attachment for style 2 DLPI drivers.
|
'_ARP'
|
unsigned integer
|
Nonzero if ARP (Address Resolution Protocol) can be done on the link; zero if it cannot, such as with PPP links. Read-only.
|
'LLNA'
|
string
|
Link name for use with the 'IFId' parameter to build the interface name.
|
'LLAd'
|
binary
|
Link hardware MAC address. This parameter is always dynamic; that is, it is set by the plug-in after the connection is active. Read-only.
|
PPP Plug-in ^TOP^
The PPP plug-in implements a Point-to-Point (PPP) link and performs PPP negotiation. It resides below the ILL plug-in in the TCP/IP stack.
The PPP plug-in has a user interface that is accessed via the PPP tab in the Connection application for Internet profiles. This tab allows the user to set certain configuration parameters such as user name, password, timeout, Maximum Receive Unit (MRU) size, authentication type, etc.
The complete list of parameters that you can set or get for the PPP plug-in is shown in Table 2.3.
Table 2.3 PPP plug-in parameters
Parameter
|
Type
|
Description
|
'LoIP'
|
string
|
Local IP address, in dotted notation. If this parameter is missing, automatic mode is assumed and the IP address is obtained from the server for this connection. This value is set by the IP Address field in the TCP/IP tab if Manual mode is chosen.
|
'ReIP'
|
string
|
Remote IP address for PPP links, in dotted notation. Set only in manual mode. If this parameter is present, a PPP link is assumed and a default route is added, using this address as a default gateway.
|
'_MTU'
|
unsigned integer
|
Maximum transmit unit in bytes. Defaults to 1500.
|
'_MRU'
|
unsigned integer
|
Maximum receive unit in bytes. Defaults to 1500.
|
'Mtic'
|
unsigned integer
|
Interface metric (defaults to 30 if not available). A metric is a value that is assigned to an IP route for a particular network interface that identifies the cost that is associated with using that route. For example, the metric can be valued in terms of link speed, hop count, or time delay. Higher metrics have the effect of making a route less favorable.
|
'DNSs'
|
string
|
List of DNS servers formatted as a list of dotted IP addresses, separated by spaces. This value is set by the DNS Servers form in the TCP/IP tab.
|
'DDev'
|
string
|
DLPI device name.
|
'ConT'
|
unsigned integer
|
Timeout in milliseconds when connecting. The default is 10 seconds (10000).
|
'TrmT'
|
unsigned integer
|
Timeout in milliseconds when disconnecting. The default is 3 seconds (3000).
|
'LCOp'
|
string
|
LCP (Link Control Protocol) options. The following options are valid (multiple options can be specified with the OR operator, and the default is all options ORed together):
-
ACFC
- Address and control field compression.
-
PFC
- Protocol field compression.
-
Magic
- Magic number (for loopback detection).
|
'Auth'
|
string
|
Allowed authentication options. The following options are valid (multiple options can be specified with the OR operator):
-
CHAP
- Challenge Handshake Authentication Protocol.
-
MSCHAP
- Microsoft Challenge Handshake Authentication Protocol.
-
PAP
- Password Authentication Protocol.
-
All
- Allow all options (default).
-
EncryptedOnly
- Allow all options that use encrypted passwords (
CHAP , MSCHAP ).
|
'ACCM'
|
unsigned integer
|
PPP asynchronous characters map. Defaults to 0x000A0000 (XON/XOFF characters).
|
'User'
|
string
|
Username.
|
'Pass'
|
string
|
Password (write-only).
|
Script Plug-in ^TOP^
The Script plug-in is associated with PPP and provides login script capability for PPP connections.
The Script plug-in has only one parameter, listed in Table 2.4.
Table 2.4 Script plug-in parameters
Parameter
|
Type
|
Description
|
'LogS'
|
binary
|
Login script.
|
Login script commands that you can use are listed in Table 2.5.
Table 2.5 Login script commands
Function
|
Command
|
Parameters
|
Example
|
Send
|
s
|
string
|
s go PPP
|
Wait for
|
w
|
string
|
w password:
|
Delay
|
d
|
seconds
|
d 1
|
Get IP
|
g
|
none
|
g
|
Prompt
|
a
|
string
|
a Enter Name:
|
Wait for prompt
|
f
|
string
|
f ID:
|
Send CR
|
n
|
none
|
n
|
Send UserID
|
u
|
none
|
u
|
Send Password
|
x
|
none
|
x
|
End
|
e
|
none
|
e
|
When setting the value of the LogS parameter, the characters in the script command string must be encoded into ASCII hex values and enclosed in square brackets. Each script command must end with the null character (00). For example, for the command "s go PPP", you would set this value: [7320676f2050505000]
The final script command string in the set must end with an additional null character, so there must be two nulls at the end (0000).
In the parameters to various login script commands, you can use the special escape sequences listed in Table 2.6. Each escape sequence, when encountered in a script command, expands to the value shown.
Table 2.6 Login script escape sequences
Escape sequence string
|
Description
|
$USERID
|
Expands to the user name.
|
$PASSWORD
|
Expands to the password.
|
^c
|
If c is one of the ASCII characters in the sequence '@' through '_', then this equals a byte value of 0 through 31, respectively.
If c is one of the ASCII characters in the sequence 'a' through 'z', then this equals a byte value of 1 through 26, respectively.
If c is any other character, this equals that character.
|
<cr>
|
Carriage return (0x0D)
|
<lf>
|
Line feed (0x0A)
|
\"
|
" (double quotation mark)
|
\^
|
^ (circumflex accent)
|
\<
|
< (less-than sign)
|
\\
|
\ (backslash)
|
DLE Plug-in ^TOP^
The DLE plug-in provides the Ethernet framing interface and resides at the lowest level, above the network hardware.
The DLE plug-in has no user configurable parameters and thus has no user interface.
The complete list of parameters that you can set or get for the DLE plug-in is shown in Table 2.7.
Table 2.7 DLE plug-in parameters
Parameter
|
Type
|
Description
|
'DDev'
|
string
|
DLPI device name.
|
'DPPA'
|
unsigned integer
|
DLPI physical point of attachment for style 2 DLPI drivers.
|
'_ARP'
|
unsigned integer
|
Nonzero if ARP (Address Resolution Protocol) can be done on the link; zero if it cannot, such as with PPP links. Read-only.
|
'DevN'
|
string
|
Name of IOS driver that will be opened when connecting the profile.
|
Examples of Network Profile Strings ^TOP^
Here is an example of a profile using the 'foo' device. It will be configured using DHCP:
P1 = "NetOut/IPIF/ILL/DLE:DevN='foo'"
Here is an example of a subprofile:
"Mydevice" = "ILL/DLE:DevN='foo'"
The following profile is equivalent to P1:
P2 = "NetOut/IPIF/Mydevice"
Here is an example of a manually configured profile with the local IP address set. The subnet mask and broadcast address will be automatically set:
P3 = "NetOut/IPIF:LoIP='192.168.1.10',GWys='192.168.1.1',DNSs='192.168.2.1',Doms='bar.org'/Mydevice"
Here is an example of a PPP connection using a direct IrDA link:
P4 = "NetOut/IPIF/ILL/PPP:User='foo',Pass='bar'/Serial:DevN='ircomm'"
Here is an example of a PPP connection with the local IP address manually set and a script:
P5 = "NetOut/IPIF/ILL/PPP:User='foo',Pass='bar',LoIP='192.168.2.10'/Script:LogS=[............]/Serial:DevN='ircomm'"
The following profile is equivalent to P5 (it will produce the same effect but is not creatable via the user interface):
P6 = "NetOut/IPIF:LoIP='192.168.2.10'/ILL/PPP:User='foo',Pass='bar'/Script:LogS=[............]/Serial:DevN='ircomm'"
Serial Plug-ins ^TOP^
There is a serial interface node and a serial plug-in that provide an interface to serial communication hardware:
Serial Interface ^TOP^
All serial profiles must start with the SerialMgr interface. This interface serves as the top-level serial component in the system. It is not a plug-in, but rather an interface, below which all other serial plug-ins must reside.
Profiles define a number of parameters for the SerialMgr interface, and these are listed in Table 2.8.
Table 2.8 SerialMgr interface parameters
Parameter
|
Type
|
Description
|
'crea'
|
unsigned integer
|
The port ID that is returned by SrmGetDeviceInfo() in DeviceInfoType.serDevCreator . This ID can be used to open a port. Profiles defining IrComm and RfComm will use the legacy IDs 'ircm' and 'rfcm', respectively.
|
'feat'
|
unsigned integer
|
Defines the port capabilities (serDevCradlePort , serDevRS232Serial , etc.), which are returned by SrmGetDeviceInfo() in DeviceInfoType.serDevFtrInfo .
|
'mbrt'
|
unsigned integer
|
Maximum baud rate supported by the port, which is returned by SrmGetDeviceInfo() in DeviceInfoType.serDevMaxBaudRate .
|
'hsbr'
|
unsigned integer
|
Always set this parameter to zero.
|
'hnam'
|
string
|
The name to be used for this port in the user interface. This name is returned by SrmGetDeviceInfo() in DeviceInfoType.serDevPortInfoStr . This name must be localized.
|
'lpid'
|
unsigned integer
|
Optional. Defines the mapping of this port to a Serial Manager logical port ID (for example, serPortCradlePort ; constants are defined in SerialMgrLib.h). There must be only one profile defining each logical port.
|
Here is an example of a profile string for a port based on a device named "SERIAL":
"SerialMgr:crea=1234,feat=0x00001000,mbrt=115200,hsbr=300,hnam='Cradle port',lpid=0/Serial:Baud=9600,FCtl=0x80000000,Bits=0x30,DevN='SERIAL'"
Serial Plug-in ^TOP^
The Serial plug-in provides an interface to serial communication hardware. It registers itself with the Connection Manager under the name "Serial".
The Serial plug-in has a user interface that is accessed via the Serial tab in the Connection application. This tab allows the user to set certain configuration parameters such as the device name, baud rate, number of data and stop bits, parity, etc.
The complete list of parameters that you can set or get for the Serial plug-in is shown in Table 2.9.
Table 2.9 Serial plug-in parameters
Parameter
|
Type
|
Description
|
'Baud'
|
unsigned integer
|
Baud rate. Standard baud rate constants are defined in termios.h. All baud rates are not supported by all serial hardware.
|
'FCtl'
|
unsigned integer
|
Flow control configuration. Specify CTSFLOW , RTSFLOW , or CRTSCTS (constants are defined in termios.h).
|
'Bits'
|
unsigned integer
|
Number of data bits. Specify CS5 , CS6 , CS7 , or CS8 (constants defined in termios.h).
|
'Stop'
|
unsigned integer
|
Number of stop bits. For 1 stop bit specify 0, or for 2 stop bits specify CSTOPB (constants defined in termios.h).
|
'Prty'
|
unsigned integer
|
Parity setting. For no parity specify 0, for even parity specify PARENB , or for odd parity specify PARENB|PARODD (constants defined in termios.h).
|
'DevN'
|
string
|
Name of IOS driver that will be opened when connecting the profile.
|
USB Plug-in ^TOP^
The USB plug-in provides an interface to USB hardware. It registers itself with the Connection Manager under the name "USBSerial".
The complete list of parameters that you can set or get for the USB plug-in is shown in Table 2.10.
Table 2.10 USB plug-in parameters
Parameter
|
Type
|
Description
|
'Func'
|
unsigned integer
|
32-bit creator code that defines what the function of the USB connection is, for example, 'sync' for HotSync.
|
'DevN'
|
string
|
Name of IOS USB serial driver that will be opened when connecting the profile. This must be USBSERIAL.
|
The USB plug-in uses the other serial plug-in parameters when creating the default USB profiles so that the profiles will mimic a serial interface. These serial paramters have no effect on the connection, however.
Infrared Plug-in ^TOP^
The Infrared plug-in provides an interface to infrared (IR) hardware. It registers itself with the Connection Manager under the name "IRIF".
The Infrared plug-in configures itself automatically and has no parameters.
Here is an example profile string for PPP over infrared:
"NetOut/IPIF/PPP:User='foo',Pass='bar'/IRIF"
Bluetooth Plug-in ^TOP^
The Bluetooth plug-in provides an interface to Bluetooth hardware. It registers itself with the Connection Manager under the name "Bluetooth".
The Bluetooth plug-in has a user interface that is accessed via the Bluetooth Connection application. This tab allows the user to set certain configuration parameters such as the Bluetooth device name, whether to authenticate the connection, and whether to encrypt the data.
The complete list of parameters that you can set or get for the Bluetooth plug-in is shown in Table 2.11.
Table 2.11 Bluetooth plug-in parameters
Parameter
|
Type
|
Description
|
'addr'
|
string
|
48-bit Bluetooth device address of the remote device formatted as six one-byte values expressed in hex and separated by colons (for example '98:76:54:ab:CD:ef'). If this parameter is not specified, then a device discovery operation is performed.
|
'cod'
|
string
|
Class-of-device. Used for filtering the devices that are displayed to the user if a discovery procedure is used to determine the remote device address. Valid values are: 'computer', 'pda', 'phone', 'modem', or 'lan'. If no class-of-device parameter is specified, then the discovery procedure displays devices of all classes.
Developers are discouraged from specifying a value for 'cod', 'cod2', and 'cod3' because there is no reliable correlation between a remote device's class of device and the services it provides.
|
'cod2'
|
string
|
A second class-of-device that takes the same values as 'cod'.
|
'cod3'
|
string
|
A third class-of-device that takes the same values as 'cod'.
|
'prot'
|
string
|
Bluetooth protocol to use, either 'l2cap' or 'rfcomm'. If not specified, then 'rfcomm' is used.
|
'intf'
|
string
|
Which standard interface, if any, to present above the Bluetooth protocol entity. Only the value 'serial' is supported.
|
'sci'
|
string
|
Service class identifier to look for in the ServiceClassIDList attribute of the remote service record. If more than one service class identifier is specified (by using the sciN parameters), they are searched in sequence one at a time. The search ends as soon as one is found.
Valid values are: 'SerialPort', 'LANAccessUsingPPP', 'DialupNetworking', 'OBEXObjectPush'; or a 128-bit UUID expressed by exactly 32 hex digits, for example, '0123456789abcdef0123456789abcdef'. (If specifying a UUID, the hex digits are not bracketed or preceded by 0x.)
If PPP is used above Bluetooth and no sciN parameter is specified, and the class-of-device is 'phone' or 'modem', then sci='DialupNetworking'. If the class-of-device is 'lan' or 'computer', then sci='LANAccessUsingPPP'.
If Serial or Telephony are used above Bluetooth and no sciN parameter is specified, then sci='SerialPort'.
|
'sci2'
|
string
|
Service class id to look for if that specified by 'sci' is not found.
|
'sci3'
|
string
|
Service class id to look for if those specified by 'sci' and 'sci2' are not found.
|
'auth'
|
string
|
Authentication required. Specify either 'yes' (default if 'encr' is set to 'yes') or 'no' (default if 'encr' is set to 'no').
|
'encr'
|
string
|
Encryption required; implies authentication is required. Specify either 'yes' or 'no' (default).
|
To determine the values for parameters whose values are not explicitly specified, the Bluetooth plug-in uses any contextual information present in the profile. That is, it looks for those values in plug-ins and interfaces to the left of Bluetooth in the profile string.
You should never programmatically create a profile containing only the Bluetooth plug-in (a Bluetooth terminal profile) because these must always be kept in sync with the Bluetooth favorites list and the Bluetooth cache information. The recommended way to create a Bluetooth terminal profile is to sublaunch the Bluetooth panel to add a new favorite device. Once the device has been added to the favorites list, you can still programmatically add or modify profile parameters, except for 'addr' and all 'codN' parameters, which must never be changed.
Telephony Plug-ins ^TOP^
There are two telephony plug-ins that provide an interface to phone hardware:
Phone Plug-in ^TOP^
The phone plug-in registers itself with the Connection Manager under the name "Phone".
The Phone plug-in has a user interface that is accessed via the Phone tab in the Connection application. This tab allows the user to choose the phone driver.
The Phone plug-in has only one parameter, listed in Table 2.12.
Table 2.12 Phone plug-in parameters
Parameter
|
Type
|
Description
|
'Drvr'
|
unsigned integer
|
The creator of the phone driver to use.
|
The DataCall plug-in registers itself with the Connection Manager under the name "DataCall".
The DataCall plug-in has a user interface that is accessed via the DataCall tab in the Connection application. This tab allows the user to set certain parameters such as the phone connection type and phone number to dial for analog connections.
The complete list of parameters that you can set or get for the DataCall plug-in is shown in Table 2.13.
Table 2.13 DataCall plug-in parameters
Parameter
|
Type
|
Description
|
'Type'
|
unsigned integer
|
Only the value 0, for analog connections, is supported.
|
'Dial'
|
string
|
The phone number to dial, for analog connections.
|