< Home < Developers < Development Support < Documentation

## 64 Script Plugin

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 64 Script Plugin Script Plugin Data Types PluginCallbackProcType PluginCmdPtr PluginCmdType PluginExecCmdType PluginInfoPtr PluginInfoType ScriptPluginLaunchCodesEnum Script Plugin Constants Command Constants Size Constants Script Plugin Functions ScriptPluginSelectorProc |  |  |  | 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, vol. II, Communications. ## Script Plugin Data Types ## PluginCallbackProcType The PluginCallbackProcType defines the procP field in PluginExecCmdType.
    typedef struct {
      ScriptPluginSelectorProcPtr selectorProcP;
    } PluginCallbackProcType, *PluginCallbackProcPtr;
#### Field Descriptions #####
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 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 #####
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 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 #####
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 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 #####
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 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 #####
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). #####
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