Update a field in an existing account.

int POPSTORE_user_update (user_context, item_list errmsg, errmsg_len, errmsg_max) POPSTORE_user_context *user_context; POPSTORE_item_list *item_list; char *errmsg; int *errmsg_len; int errmsg_max;

Arguments

user_context

User context to update. Used for input and output.

item_list

Item list describing the updates to perform. Used for input only.

errmsg

Address of character array that POPSTORE_user_update can put an error message into if the password change fails.

errmsg_len

Address of an integer that POPSTORE_user_update can write the length of the error message that it put into errmsg.

errmsg_max

The size of the array that errmsg points to.

Description

One or more fields in a popstore profile file can be changed by calling POPSTORE_user_update. The fields to update and the new values to use are described using an array of item descriptors, each of which specifies an action and provides the information needed to perform that action. The list of item descriptors is terminated with an entry with the POPSTORE_SET_END item code. The list of item descriptors is referred to as an item list. When the item list is successfully processed, both the on-disk and in-memory profile is updated and the POPSTORE_SUCCESS item code is returned.⁶ Should an error occur while processing the item list, no updates are made to the underlying user profile file, and POPSTORE_user_end returns an error status. Depending upon the nature of the error, the in-memory profile data can have been changed. Note that the username field can not be changed with POPSTORE_user_update. Use POPSTORE_user_copy_d with do_rename=1 to change the username field for an existing account. Moreover, the MANAGE usage flag can not be set or cleared without first calling POPSTORE_manage to authorize such activity. The item_list argument is a pointer to an array of one or more item descriptors whose type is given by the POPSTORE_item_list structure shown below:

typedef struct { int item_code; void *item_address; int item_length; } POPSTORE_item_list;

The interpretation of the three fields in an item descriptor is as follows:

POPSTORE_item_list item descriptor fields

item_code

A signed, longword integer containing a user-supplied symbolic code specifying an action to be taken by PMDF_user_update. A description of each item code follows this list of item descriptor fields.

item_address

A pointer to the value to use in updating the profile field indicated by the associated item_code. Not all actions require that a value be supplied for the item_address field.

item_length

A signed, longword integer containing the user-supplied length of the data pointed at by item_address. Not all actions require that an item_length be specified.

The item_code values accepted by POPSTORE_user_update are as follows:

POPSTORE_user_update item codes

POPSTORE_SET_CHAIN

This item code can be used to direct the item list processing to another item list. The value of the item_address field should be a pointer to another POPSTORE_item_list structure. The item_length field is ignored.

POPSTORE_SET_END

The end of the item list is indicated by this item code. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_DELETE

Set the DELETE usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_DISMAIL

Set the DISMAIL usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_DISUSER

Set the DISUSER usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_LOCKPWD

Set the LOCKPWD usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_MANAGE

Set the MANAGE usage flag. The item_address and item_length fields are ignored. A prior call to POPSTORE_manage must be made in order to permit setting the MANAGE flag.

POPSTORE_SET_FLAGS_NO_DELETE

Clear the DELETE usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_NO_DISMAIL

Clear the DISMAIL usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_NO_DISUSER

Clear the DISUSER usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_NO_LOCKPWD

Clear the LOCKPWD usage flag. The item_address and item_length fields are ignored.

POPSTORE_SET_FLAGS_NO_MANAGE

Clear the MANAGE usage flag. The item_address and item_length fields are ignored. A prior call to POPSTORE_manage must be made in order to permit clearing the MANAGE flag.

POPSTORE_SET_GROUP_NAME

Set the value of the group field. The value of the item_address field must point to a string value. The value of the item_length field must be the length in bytes of the string value. That length can not exceed POPSTORE_MAX_GROUP_LEN bytes.

POPSTORE_SET_LAST_BILLING

Set the value for the last billing time field. The value of the item_address field must point to a time_t value expressing the last billing time as the number of seconds since 1 January 1970. The item_length field is ignored.

POPSTORE_SET_LAST_CONNECT

Set the value of the last connect time field. The value of the item_address field must point to a time_t value expressing the last connect time as the number of seconds since 1 January 1970. The item_length field is ignored.

POPSTORE_SET_LAST_DISCONNECT

Set the value of the last disconnect time field. The value of the item_address field must point to a time_t value expressing the last disconnect time as the number of seconds since 1 January 1970. The item_length field is ignored.

POPSTORE_SET_LAST_PWD_CHANGE

Set the value of the last password change time field. The value of the item_address field must point to a time_t value expressing the last password change time as the number of seconds since 1 January 1970. Use a value of zero to indicate that the account password is pre-expired. The item_length field is ignored.

POPSTORE_SET_MESSAGE_COUNT

Set the value of the message count field. If the value, V, is less than the count of currently stored messages, M, then the first M-V stored messages will be deleted. The value of the item_address field must point to a uint32 value denoting the new message count. The item_length field is ignored.

POPSTORE_SET_NOOP

This signifies an item descriptor which should be ignored. The item_address and item_length fields are ignored.

POPSTORE_SET_OVERDRAFT

Set the overdraft storage quota. The value of the item_address field must point to a uint32 value expressing the overdraft storage quota in units of bytes. The item_length field is ignored.

POPSTORE_SET_OWNER

Set the value of the owner field. The value of the item_address field must point to a string value. The value of the item_length field must be the length in bytes of the string value. That length can not exceed POPSTORE_MAX_OWN_LEN bytes.

POPSTORE_SET_PASSWORD

Set the value of the password field. The value of the item_address field must point to a string value. The value of the item_length field must be the length in bytes of the string value. That length can not exceed POPSTORE_MAX_PWD_LEN bytes.

POPSTORE_SET_PAST_BLOCK_DAYS

Set the past block days accounting field. The value of the item_address field must point to a uint32 value expressing the new past block days value to use. The item_length field is ignored. Note that when the past block days field is set, the past block days remainder field is set to a value of zero.

POPSTORE_SET_PRIVATE

Set the value of the site-defined private data field. The value of the item_address field must point to a string value. The value of the item_length field must be the length in bytes of the string value. That length can not exceed POPSTORE_MAX_PRIV_LEN bytes.

POPSTORE_SET_QUOTA

Set the primary storage quota. The value of the item_address field must point to a uint32 value expressing the primary storage quota in units of bytes. The item_length field is ignored.

POPSTORE_SET_TOTAL_CONNECT

Set the elapsed total connect time. The value of the item_address field must point to a uint32 value expressing the elapsed total connect time in units of seconds. The item_length field is ignored.

Return Values

POPSTORE_SUCCESS	Normal, successful completion.
POPSTORE_BADITMCOD	Unrecognized item code specified. No changes made to the on-disk or in-memory user information.
POPSTORE_BADLENGTH	Length of a string value is less than zero. No changes made to the on-disk or in-memory user information.
POPSTORE_CMDBADVAL	Attempt made to set the message count to a value exceeding the count of currently stored messages. No changes made to the on-disk or in-memory user information.
POPSTORE_FILOPNERR	Unable to open the profile file for reading and writing. No changes made to the on-disk or in-memory user information.
POPSTORE_INSUFPRIV	The process lacks SYSLCK privilege (OpenVMS only). No changes made to the on-disk or in-memory user information.
POPSTORE_LCKOPNERR	Unable to obtain lock information for the profile file. No changes made to the on-disk or in-memory user information.
POPSTORE_LOCKERROR	Unable to obtain a lock for the profile file. No changes made to the on-disk or in-memory user information.
POPSTORE_NOPRIVILEGE	Process is not allowed to set or clear the MANAGE usage flag without a prior call to POPSTORE_manage. No changes made to the on-disk or in-memory user information.
POPSTORE_NULLCONTEXT	user_context is null. No changes made to the on-disk or in-memory user information.
POPSTORE_NULLPROFILE	user_context->profile context is null. No changes made to the on-disk or in-memory user information.
POPSTORE_PWDLOCKED	Cannot change the password; password is locked. No changes made to the on-disk or in-memory user information.
POPSTORE_READERROR	An error occurred while reading data from the profile file. No changes made to the on-disk or in-memory user information.
POPSTORE_SEEKERROR	An error occurred while seeking to a location in the profile file. No changes made to the on-disk or in-memory user information.
POPSTORE_TOOLONG	Length of string value exceeds permitted length. No changes made to the on-disk or in-memory user information.
POPSTORE_WRITERROR	An error occurred while writing data to the profile file. No changes made to the on-disk profile information; in-memory user information has been changed.