This chapter describes the login script plugin support. You write a plugin to add to the list of available login script commands in the Network preferences panel. This chapter covers:
The header file ScriptPlugin.h
declares the API described in this chapter.
For more information on the script plugin, see the section "Extending the Network Login Script Support" in the "Network Communication" chapter of the Palm OS Programmer's Companion, vol. II, Communications.
Script Plugin Data Types
PluginCallbackProcType Struct
Purpose
The PluginCallbackProcType
defines the procP
field in PluginExecCmdType
.
Prototype
typedef struct { ScriptPluginSelectorProcPtr selectorProcP; } PluginCallbackProcType, *PluginCallbackProcPtr;
Fields
-
selectorProcP
- The address of a selector-based callback function for accessing the functionality of the network interface. Each network interface provides it own
ScriptPluginSelectorProc
function. SeeScriptPluginSelectorProc()
.
PluginCmdPtr Typedef
Purpose
The PluginCmdPtr
type defines a pointer to a PluginCmdType
structure.
Prototype
typedef PluginCmdType *PluginCmdPtr;
PluginCmdType Struct
Purpose
The PluginCmdType
structure specifies the name of a command.
Prototype
typedef struct { Char commandName[pluginMaxCmdNameLen + 1]; Boolean hasTxtStringArg; UInt8 reserved; } PluginCmdType;
Fields
- The name of the command. This string appears in the pull-down list in the Network preferences panel's script view.
- The pull-down list contains all available commands from all plugins. Make sure that your command name is unique and as short as possible.
-
true
if the command takes an argument. In this case when the user selects this command, the Network preferences panel displays a field next to the command name where the user should enter the argument. This argument is passed in thetxtStringArg
field inPluginExecCmdType
when the command is to be executed.
PluginExecCmdType Struct
Purpose
The PluginExecCmdType
structure defines the parameter block for the scptLaunchCmdExecuteCmd
launch code. This structure specifies which command is to be executed and provides any necessary arguments for the command. Your plugin should respond by executing the command.
Prototype
typedef struct { Char commandName[pluginMaxCmdNameLen + 1]; Char txtStringArg [pluginMaxLenTxtStringArg + 1]; PluginCallbackProcPtr procP; void *handle; } PluginExecCmdType, *PluginExecCmdPtr;
Fields
-
commandName
- The command's name. This is the string that appears in the pull-down list in the script view of the Network preferences panel.
-
txtStringArg
- If the command takes an argument, this field provides the argument as a string. A
NULL
value means either that the user did not provide a value, or that you didn't specify that the command takes an argument. -
procP
- A pointer to a
PluginCallbackProcType
structure, which identifies the network interface function that the plugin can use to execute the command. -
handle
- Handle to information specific to a particular connection. You must pass this value when you call the function pointed to by
procP
.
PluginInfoPtr Typedef
Purpose
The PluginInfoPtr
type defines a pointer to a PluginInfoType
structure.
Prototype
typedef PluginInfoType *PluginInfoPtr;
PluginInfoType Struct
Purpose
The PluginInfoType
structure is the parameter block for the scptLaunchCmdListCmds
launch code. When your plugin receives the launch code, the PluginInfoType
structure is empty. Your plugin should fill in the PluginInfoType
and return it. The system uses the information returned to construct the pull-down list of available script commands and build a table of which plugin will execute which script command.
Prototype
typedef struct { Char pluginName[pluginMaxModuleNameLen + 1]; UInt16 numOfCommands; PluginCmdType command[pluginMaxNumOfCmds]; } PluginInfoType;
Fields
-
pluginName
- A name that the system can use to identify your plugin. This is typically the same name you give the PRC file.
-
numOfCommands
- The number of commands that your plugin defines. The maximum allowed is
pluginMaxNumOfCmds
. -
command
- An array of
PluginCmdType
structures that provide information about the commands that your plugin defines.
ScriptPluginLaunchCodesEnum Enum
Purpose
The ScriptPluginLaunchCodesEnum
defines the launch codes for the script plugin. Your script plugin's PilotMain()
function should respond to the launch codes defined in this enum.
Prototype
typedef enum { scptLaunchCmdDoNothing = sysAppLaunchCmdCustomBase, scptLaunchCmdListCmds, scptLaunchCmdExecuteCmd } ScriptPluginLaunchCodesEnum;
Constants
-
scptLaunchCmdDoNothing
- This launch code is a no-op supplied only to provide a beginning value for the script plugin launch codes. It is not necessary to respond to this launch code.
-
scptLaunchCmdListCmds
- Provide information about the commands that your plugin executes. See
PluginInfoType
. -
scptLaunchCmdExecuteCmd
- Execute the specified command.
- This launch code is received when the system is executing a user's login script during a network connection attempt. Your plugin should respond by executing the command provided in the
PluginExecCmdType
parameter block.
Script Plugin Constants
Command Constants
The following constants identify the available commands that the network interface can perform for you. These commands are building blocks that you use to create your own script commands. To perform one of these tasks, pass the constant value as an argument to the network interface's callback function (ScriptPluginSelectorProc()
).
Size Constants
The following table lists constants that control the size of strings in your plugin and the size of the plugin itself.
Script Plugin Functions
ScriptPluginSelectorProc Function
Purpose
A function provided by the network interface for the purpose of performing script commands.
Declared In
ScriptPlugin.h
Prototype
Err ( *ScriptPluginSelectorProcPtr ) ( void *handle, UInt16 command, void *dataBufferP, UInt16 *sizeP, UInt16 *dataTimeoutP, void *procAddrP )
Parameters
-
→
handle
- Handle to information specific to a particular connection.
-
→
command
- The command to be executed. See "Command Constants" for a list of possible values. The rest of the parameters to this callback function are interpreted differently based on the value of the
command
parameter. See the table in the "Comments" section for specifics. -
↔
dataBufferP
- A pointer to arguments to pass to the command or a pointer to data returned by the command. See the "Comments" section below.
-
↔
sizeP
- The size of
dataBufferP
. -
→
dataTimeoutP
- Number of seconds to wait for the command to execute. 0 means wait forever. Applies only to commands that request information from the network.
-
→
procAddrP
- Pointer to a user interface callback function that the network interface should call to complete the function. Used only by
pluginNetLibCallUIProc
. This function should take one argument of the same type that you pass todataBufferP
and should returnvoid
.
Returns
Returns 0 upon success, or an error condition upon failure. If an error condition is returned, your plugin should stop processing and return the error condition from its PilotMain()
.
Comments
When your plugin receives the scptLaunchCmdExecuteCmd
launch code, the parameter block contains the command's name, its text string argument (if any), and a pointer to the network interface's callback function. You should use this callback function any time you need to communicate with the network library, the user, or the host computer during execution of your command.
The callback function takes as arguments the handle to information about this connection (which is also passed in the launch code's parameter block), and the command that the service should execute. The rest of the parameters are interpreted differently based on what the value the command argument is. See the table below.