Process a popstore management command.

format

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 wanting to produce their own management interfaces can 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 can 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 can 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 can want 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 can be signified by returning POPSTORE_ABORT .

Return Values

POPSTORE_SUCCESS	Normal, successful completion.
POPSTORE_BADARG	Null value received for the out_proc argument.
POPSTORE_ERRORS	The command was parsed and executed; execution of the command resulted in some errors which were reported via the output_proc procedure.
POPSTORE_AUTHFAIL	Invalid password or username supplied. The command was not executed.
POPSTORE_BADHEXVAL	The command contained an illegal hexadecimal encoded character. The command was not executed.
POPSTORE_CMDTOOLONG	The command contained too many name=value pairs. The command was not executed.
POPSTORE_CMDUNKOWN	The command contained an unrecognized right-hand-side in a name=value pair. The command was not executed.
POPSTORE_CMDUNKOWNL	The command contained an unrecognized left-hand-side in a name=value pair. The command was not executed.
POPSTORE_NOMANAGE	Specified account lacks management privileges. The command was not executed.
POPSTORE_PWDREQUIRED	A username and password are required. The command was not executed.
POPSTORE_VMERROR	Insufficient virtual memory. The command was not executed.
	Any error returned by the output_proc procedure.
	Any other popstore error.