Set the value of a field in a POPSTORE_user_context structure.

int POPSTORE_user_create_set (user_context, operation, ...) POPSTORE_user_context **user_context; int operation;

Arguments

user_context

Address of a pointer to a POPSTORE_user_context structure in which to set the specified items. Used for input and output.

operation

Operation to perform indicating which field in the data structure to set. Used for input only.

Description

POPSTORE_user_create_set is used to set fields in a POPSTORE_user_context structure which will then subsequently be used with POPSTORE_user_create to create a new popstore account. POPSTORE_user_create_set cannot be used to change values for an existing account; use POPSTORE_user_update for such purposes. An example of using POPSTORE_user_create and POPSTORE_user_create_set is given in Example 12-1. POPSTORE_user_create_set is used by calling it repeatedly to set the values of different fields in a POPSTORE_user_context structure which is the core structure representing a user account. When setting fields for a new account, set the user_context variable to NULL prior to the first call to POPSTORE_user_create_set; e.g.,

POPSTORE_user_context *user_context; user_context = NULL; istat = POPSTORE_user_create_set (&user_context, POPSTORE_SET_USERNAME, username, strlen (username)); istat = POPSTORE_user_create_set (&user_context, POPSTORE_SET_PASSWORD, password, strlen (password));

On the first call, a context will be allocated and initialized and its address returned in user_context. This context is then used with subsequent calls for this particular account. When POPSTORE_user_create is called, the account is then created and the context deallocated. To create another new account, again set the user_context to NULL prior to calling POPSTORE_user_create_set. If you want to abort creating an account, use POPSTORE_user_create_dispose to dispose of a context created by POPSTORE_user_create_set. The operation argument specifies the operation to perform. The accepted values for operation are listed in Table 12-4. Depending upon the selected operation, one or two additional arguments can need to be specified when calling POPSTORE_user_create_set; refer to Table 12-4 for specific details. Note that the MANAGE usage flag cannot be set or cleared without first calling POPSTORE_manage to authorize such activity.

Table 12-4 POPSTORE_user_update Operations

Item codes requiring no additional call arguments
Operation	Usage
POPSTORE_SET_FLAGS_DELETE	Set the DELETE usage flag.
POPSTORE_SET_FLAGS_DISMAIL	Set the DISMAIL usage flag.
POPSTORE_SET_FLAGS_DISUSER	Set the DISUSER usage flag.
POPSTORE_SET_FLAGS_LOCKPWD	Set the LOCKPWD usage flag.
POPSTORE_SET_FLAGS_MANAGE	Set the MANAGE usage flag; requires a prior call to POPSTORE_manage.
POPSTORE_SET_FLAGS_MIGRATED	Set the MIGRATED usage flag.
POPSTORE_SET_FLAGS_PWD_ELSEWHERE	Set the PWD_ELSEWHERE usage flag.
POPSTORE_SET_FLAGS_NO_DELETE	Clear the DELETE usage flag.
POPSTORE_SET_FLAGS_NO_DISMAIL	Clear the DISMAIL usage flag.
POPSTORE_SET_FLAGS_NO_DISUSER	Clear the DISUSER usage flag.
POPSTORE_SET_FLAGS_NO_LOCKPWD	Clear the LOCKPWD usage flag.
POPSTORE_SET_FLAGS_NO_MANAGE	Clear the MANAGE usage flag; requires a prior call to POPSTORE_manage.
POPSTORE_SET_FLAGS_NO_MIGRATED	Clear the MIGRATED usage flag.
POPSTORE_SET_FLAGS_NO_PWD_ELSEWHERE	Clear the PWD_ELSEWHERE usage flag.
POPSTORE_SET_STORE_TYPE_IMAP	Set the message store type to be IMAP.
POPSTORE_SET_STORE_TYPE_NATIVE	Set the message store type to be NATIVE.
POPSTORE_SET_STORE_TYPE_POP	Set the message store type to be POP.
Item codes requiring one additional call argument of type time_t
Item code	Usage
POPSTORE_SET_LAST_BILLING	Set the value for the last billing time field. The value of this field is a C time_t type expressing the number of seconds since 1 January 1970 and is passed as the third argument. Note that POPSTORE_user_add will override this field with the current time.
POPSTORE_SET_LAST_CONNECT	Set the value of the last connect time field. The value of this field is a C time_t type expressing the number of seconds since 1 January 1970 and is passed as the third argument. Use a value of zero to indicate no prior connections have been made.
POPSTORE_SET_LAST_DISCONNECT	Set the value of the last disconnect time field. The value of this field is a C time_t type expressing the number of seconds since 1 January 1970 and is passed as the third argument. Use a value of zero to indicate that no prior connections have been made.
POPSTORE_SET_LAST_PWD_CHANGE	Set the value of the last password change time field. The value of this field is a C time_t type expressing the number of seconds since 1 January 1970 and is passed as the third argument. Use a value of zero to indicate that the account password is pre-expired.
Item codes requiring one additional call argument of type uint32
Item code	Usage
POPSTORE_SET_OVERDRAFT	Set the overdraft storage quota. The value of this field is measured in units of bytes.
POPSTORE_SET_PAST_BLOCK_DAYS	Set the past block days accounting field. The value of this field is measured in units of block days where a block is 1024 bytes.
POPSTORE_SET_QUOTA	Set the primary storage quota.
POPSTORE_SET_RECEIVED_BYTES	Set the cumulative count of received message bytes.
POPSTORE_SET_RECEIVED_MESSAGES	Set the cumulative count of received messages.
POPSTORE_SET_TOTAL_CONNECT	Set the elapsed total connect time. The value of this field is measured in units of seconds.
POPSTORE_SET_TOTAL_CONNECTIONS	Set the elapsed count of total connections time.
Item codes requiring two additional call arguments of types int, char *
Item code	Usage
POPSTORE_SET_GROUP_NAME	Set the value of the group field. The third argument to POPSTORE_user_data_set should be the length in bytes of the string value and the fourth argument a pointer to the string value. The length of the string value can not exceed POPSTORE_MAX_GROUP_LEN bytes.
POPSTORE_SET_OWNER	Set the value of the owner field. The third argument to POPSTORE_user_data_set should be the length in bytes of the string value and the fourth argument a pointer to the string value. The length of the string value can not exceed POPSTORE_MAX_OWN_LEN bytes.
POPSTORE_SET_PASSWORD	Set the value of the password field. The third argument to POPSTORE_user_data_set should be the length in bytes of the string value and the fourth argument a pointer to the string value. The password should be supplied in plain text form; it will automatically be encrypted. The length of the string value can not exceed POPSTORE_MAX_PWD_LEN bytes.
POPSTORE_SET_PRIVATE	Set the value of the site-defined private data field. The third argument to POPSTORE_user_data_set should be the length in bytes of the string value and the fourth argument a pointer to the string value. The length of the string value can not exceed POPSTORE_MAX_PRIV_LEN bytes.
POPSTORE_SET_USERNAME	Set the value of the username field. The third argument to POPSTORE_user_data_set should be the length in bytes of the string value and the fourth argument a pointer to the string value. The length of the string value can not exceed POPSTORE_MAX_USER_LEN bytes.

Return Values

POPSTORE_SUCCESS	Normal, successful completion.
POPSTORE_BADARG	Unrecognized value specified for operation.
POPSTORE_BADLENGTH	Negative value specified for a length argument.
POPSTORE_NOPRIVILEGE	An attempt was made to set or clear the MANAGE flag without prior authorization via a POPSTORE_manage call.
POPSTORE_TOOLONG	String value exceeds maximum allowed length.
POPSTORE_VMERROR	Insufficient virtual memory. Operation failed; no context created.