Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

68    Script Plugin

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

PluginCallbackProcType Struct ^TOP^

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. See ScriptPluginSelectorProc().

PluginCmdPtr Typedef ^TOP^

Purpose

The PluginCmdPtr type defines a pointer to a PluginCmdType structure.

Prototype

typedef PluginCmdType *PluginCmdPtr;

PluginCmdType Struct ^TOP^

Purpose

The PluginCmdType structure specifies the name of a command.

Prototype

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

Fields

commandName

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.

hasTxtStringArg

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 the txtStringArg field in PluginExecCmdType when the command is to be executed.

reserved

Reserved for future use.

PluginExecCmdType Struct ^TOP^

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 ^TOP^

Purpose

The PluginInfoPtr type defines a pointer to a PluginInfoType structure.

Prototype

typedef PluginInfoType *PluginInfoPtr;

PluginInfoType Struct ^TOP^

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 {
CharpluginName[pluginMaxModuleNameLen + 1];
UInt16numOfCommands;
PluginCmdTypecommand[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 ^TOP^

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 ^TOP^

Command Constants ^TOP^

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 ^TOP^

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 ^TOP^

ScriptPluginSelectorProc Function ^TOP^

Purpose

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

Declared In

ScriptPlugin.h

Prototype

Err (
   *ScriptPluginSelectorProcPtr
) (
   void*handle,
   UInt16command,
   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.

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.

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