57 Script Plugin

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:

• Script Plugin Data Types
  
  
• Script Plugin Constants
  

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.

Script Plugin Data Types

PluginCallbackProcType

The PluginCallbackProcType defines the procP field in PluginExecCmdType.

typedef struct {

    ScriptPluginSelectorProcPtr selectorProcP;
} PluginCallbackProcType, *PluginCallbackProcPtr;

Field Descriptions

PluginCmdPtr

The PluginCmdPtr type defines a pointer to a PluginCmdType structure.

typedef PluginCmdType * PluginCmdPtr;

PluginCmdType

The PluginCmdType structure specifies the name of a command.

typedef struct {

    Char commandName[pluginMaxCmdNameLen + 1];
    Boolean hasTxtStringArg;
    UInt8 reserved;
} PluginCmdType;

Field Descriptions

PluginExecCmdType

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.

typedef struct {

    Char commandName[pluginMaxCmdNameLen + 1];
    Char txtStringArg
[pluginMaxLenTxtStringArg + 1];
    PluginCallbackProcPtr procP;
    void * handle;
} PluginExecCmdType, *PluginExecCmdPtr;

Field Descriptions

PluginInfoPtr

The PluginInfoPtr type defines a pointer to a PluginInfoType structure.

typedef PluginInfoType * PluginInfoPtr;

PluginInfoType

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.

typedef struct {

    Char pluginName[pluginMaxModuleNameLen + 1];
    UInt16 numOfCommands;
    PluginCmdType command[pluginMaxNumOfCmds];
} PluginInfoType;

Field Descriptions

ScriptPluginLaunchCodesEnum

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.

typedef enum {

    scptLaunchCmdDoNothing =
    sysAppLaunchCmdCustomBase,
    scptLaunchCmdListCmds,
    scptLaunchCmdExecuteCmd
} ScriptPluginLaunchCodesEnum;

Value Descriptions

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).

Constant	Value	Description
pluginNetLibDoNothing	0	For debugging purposes.
pluginNetLibReadBytes	1	Read the specified number of bytes from the open connection.
pluginNetLibWriteBytes	2	Write the specified number of bytes to the open connection.
pluginNetLibGetUserName	3	Get the user name from the network service profile.
pluginNetLibGetUserPwd	4	Get the user's password from the network service profile.
pluginNetLibCheckCancelStatus	5	Check to see if the user canceled the connection.
pluginNetLibPromptUser	6	Prompt the user for input.
pluginNetLibConnLog	7	Write a string to the network service's connection log.
pluginNetLibCallUIProc	8	Have the network interface call a function in your plugin that displays UI.
		Use this command if you need to display a more complicated user interface than the simple user prompt that the network interface provides.
pluginNetLibGetSerLibRefNum	9	Obtain the serial library's reference number. You need the reference number to perform any serial library commands, which you might need to perform more complex work with the connection port.

Size Constants

The following table lists constants that control the size of strings in your plugin and the size of the plugin itself.

Constant	Value	Description
pluginMaxCmdNameLen	15	The maximum length for the command's name, not including the terminating NULL character. This is the string displayed to the user in the pull-down menu.
pluginMaxModuleNameLen	15	The maximum length for the plugin's name (not including the terminating NULL character), which is typically the name of the PRC file as well.
pluginMaxNumOfCmds	10	The maximum number of commands that your plugin can define.
pluginMaxLenTxtStringArg	63	The maximum length of the argument that each command can take, not including the terminating NULL character.

Script Plugin Functions

ScriptPluginSelectorProc

Purpose

A function provided by the network interface for the purpose of performing script commands.

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 to dataBufferP and should return void.

Result

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.

pluginNetLib	dataBufferP	sizeP	dataTimeOutP	procAddrP
DoNothing	N/A	N/A	N/A	N/A
ReadBytes	On return, contains the bytes that were read.	On input, contains the number of bytes to read.	Number of seconds to wait before timing out the operation.	N/A
		On return, contains the number of bytes actually read.
WriteBytes	On input, contains the data to send.	On input, contains the number of bytes to send.	Number of seconds to wait for a response before canceling.	N/A
		On return, contains the number of bytes actually sent.
UserName	On return, contains the user's name	On return, contains the size of the string pointed to by dataBufferP.	N/A	N/A
UserPwd	On return, contains the user's password.	On return, contains the size of the string pointed to by dataBufferP.	N/A	N/A
CheckCancel Status	On return, the Boolean value true if the user canceled the command, false otherwise.	Size of Boolean.	N/A	N/A
PromptUser	On input, the prompt to display. On return, the text that the user entered.	On input and on return, the size of the string pointed to by dataBufferP.	N/A	N/A
ConnLog	The string that should be written to the log.	N/A	N/A	N/A
CallUIProc	A pointer to a structure to pass to your callback function as a parameter. This structure should contain a handle to the form to be displayed, plus any other necessary information.	N/A	N/A	A pointer to a function in your plugin that displays the form.
GetSerLib RefNum	On return, contains the serial library's reference number.	N/A	N/A	N/A