PMDF popstore & MessageStore Manager's Guide
PMDF-POP-6.0

Process a popstore management command.

int POPSTORE_command_d (command, command_len, 
                        password_required, 
                        domain, domain_len 
                        user, user_len, 
                        password, password_len, 
                        usage, usage_len, 
                        out_info, out_info_len, 
                        context, output_proc) 
      char  *command; 
      int    command_len; 
      int    password_required 
      char  *domain; 
      int    domain_len; 
      char  *user; 
      int    user_len; 
      char  *password; 
      int    password_len; 
      char  *usage; 
      int    usage_len; 
      char  *out_info; 
      int   *out_info_len; 
      void  *context; 
      int  (*output_proc)(); 

ARGUMENTS

command

The command to process. Used for input only.

command_len

Length in bytes of the command specified with command. Used for input only.

password_required

Boolean flag indicating whether or not password authentication is required in order to process the command. Used for input only.

domain

Name of the user domain associated with the user user. Supply a value of NULL to indicate the default domain. Used for input only.

domain_len

Length in bytes of the user domain name, domain. Supply a value of zero to indicate the default domain. Used for input only.

user

Name of the popstore user account to authenticate against when password authentication is required. Used for input only.

user_len

Length in bytes of the username specified with user. Used for input only.

password

User-supplied, plain text password to use when performing a password authentication. Used for input only.

password_len

Length in bytes of the plain text password specified with password. Used for input only.

usage

Usage description to be passed to site-supplied logging subroutines explaining the usage. Used for input only.

usage_len

Length in bytes of the usage description specified with usage. Used for input only.

out_info

Output buffer to receive post-processing information. Used for output only.

out_info_len

On input, the maximum length in bytes of the buffer pointed at by out_info. On output, the length in bytes of the information placed in the out_info buffer. Used for input and output.

context

Pointer to private client data to be passed to the client-supplied output_proc procedure. Used for input only.

output_proc

Address of a client-supplied subroutine to receive command processing output. Used for input only.

DESCRIPTION

The management commands documented in Chapter 4 are processed by the POPSTORE_command_d subroutine. Sites wishing to produce their own management interfaces may do so by generating management commands in the URL format described in Chapter 4 and then invoking POPSTORE_command to process those commands. The commands should reference site-supplied formatting files which then format the command results in the desired format.² When called, POPSTORE_command_d will use the active privileges of the caller to access and manipulate the popstore. The password_required argument may be used to implement a utility which itself has privileges but requires, for operation, that the user know the username and password of a popstore account with management privileges. When a non-zero value is supplied for password_required, values for the user, user_len, password, and password_len arguments must be supplied. The supplied plain text password will be authenticated against the specified account. If the password is correct and the account has the MANAGE usage flag set, then the indicated command will be processed. Otherwise, a POPSTORE_AUTHFAIL or POPSTORE_NOMANAGE error will be returned. Moreover, the account will only be allowed to perform management functions on other accounts within the same management group. When user and user_len arguments are supplied, the operation to be undertaken will be restricted to accounts within the same management group and subgroups of user. This behavior is regardless the setting of the password_required argument. On return from calling POPSTORE_command, the out_info buffer will contain the name of the formatting file associated with either the processed command's on_success or on_error parameter. If the command was successfully processed, then the buffer will contain the value specified with the command's on_success parameter. If the command was not successfully processed, then the value specified by the on_error parameter will be returned. If you do not care to have this information returned, specify a null value for out_info or out_info_len or both. The output_proc procedure is called repeatedly to received lines of output generated as a result of processing the command. The procedure takes the form

int output_proc (context, data, data_len, is_eol, is_literal, 
                 is_error) 
      void *context; 
      char *data; 
      int   data_len; 
      int   is_eol; 
      int   is_literal; 
      int   is_error; 

where the arguments to output_proc are as follows:

context	Pointer to the private client data supplied as input to POPSTORE_command.
data	Data to output. This string may not be null terminated.
data_len	Length in bytes of the data pointed at by data.
is_eol	When is_eol has a non-zero value, the output_proc procedure may wish to output an end-of-line after this batch of formatted data.
is_literal	When is_literal has a non-zero value, the output_proc procedure should not apply any quoting to the output data. The output data is literal data which was contained within the formatting file.
is_error	When is_error has a non-zero value, the output data is an error message relating to the processed command.

Upon successful completion, output_proc should return the value POPSTORE_SUCCESS. In the event of an error, some value other than POPSTORE_SUCCESS should be returned. A user-requested abort may be signified by returning POPSTORE_ABORT.

Note

² This is precisely how the Web-based and command line oriented management utilities are implemented.