PMDF popstore & MessageStore Manager's Guide
Previous Contents Index

POPSTORE_user_list_d

Return one-by-one the usernames associated with each account.

format


int POPSTORE_user_list_d (list_context, pattern, pattern_len, 
                          domain, domain_len, group, 
                          group_len, user, user_len, 
                          max_user_len) 
      POPSTORE_list_context **list_context; 
      char                   *pattern; 
      int                     pattern_len; 
      char                   *domain; 
      int                     domain_len; 
      char                    group; 
      int                     group_len; 
      char                   *user; 
      int                    *user_len; 
      int                     max_user_len;

Arguments

user_context

List context maintained by POPSTORE_user_list_d. Used for input and output.

pattern

Optional username pattern. Used for input only.

pattern_len

Length in bytes of the optional username pattern, pattern . Used for input only.

domain

Name of the user domain to use. 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.

group

Optional name of a management group to confine the listing to. Used for input only.

group_len

Length in bytes of the optional group name, group . Used for input only.

user

Buffer to receive the returned username. Length of this buffer should be at least POPSTORE_MAX_USER_LEN+1 bytes long. Used for output only.

user_len

Length in bytes of the username returned in user . Used for output only.

max_user_len

Maximum length in bytes of the buffer, user . Used for input only.

Description

POPSTORE_user_list_d can be used to obtain one at a time the usernames associated with each popstore account. To call POPSTORE_user_list_d, you must have a variable of type "POPSTORE_list_context *" available, the address of which you specify with the list_context argument. Prior to calling POPSTORE_user_list_d for the first time, set the value of that pointer variable to null. That will signify to POPSTORE_user_list_d that this is the start of a listing. POPSTORE_user_list_d will create a context and point your pointer variable at that context. Repeatedly call POPSTORE_user_list_d to obtain each username. When there are no more usernames to return, the context will be deallocated and POPSTORE_EOM returned. Sample code is provided in Example 12-3 The optional group and group_len arguments can be used to restrict the listing to just those accounts contained within the specified management group and any subgroups thereof. The group name specification can not contain wild card characters. If you do not want to restrict a listing, then specify null and 0 for these two parameters. The optional pattern and pattern_len arguments can be used to specify a pattern which the returned usernames must match. The pattern can contain wild card characters. For example, to list all accounts with usernames starting with the letter "z" supply the string value "z*" and length 2 for these two arguments. To return all usernames, instead supply the values null and 0. To prematurely end a listing, call POPSTORE_user_list_abort so as to properly dispose of the listing context. While POPSTORE_user_list_d can be used to produce lists of user accounts, often using POPSTORE_format_profiles is more appropriate. POPSTORE_user_list_d is intended for situations where code needs to be able to obtain, one at a time, the usernames for all or some accounts. For instance, to periodically bill all user accounts with POPSTORE_user_billing_d.

Return Values

POPSTORE_SUCCESS Normal, successful completion.
POPSTORE_BADARG Bad value supplied for the list_context, user, user_len, or max_user_len argument.
POPSTORE_DBBADLENGTH Retrieved a record from the database which has an unexpected length. In practice, this error should never occur.
POPSTORE_DBERR An unknown error occurred while attempting to read from the user database. In practice, this error should never occur.
POPSTORE_DBOPNERR Unable to open the user database.
POPSTORE_DBMISSING User database does not exist; create it with the X-BUILD-USER-DB command of the command-line popstore management utility.
POPSTORE_EOM No more usernames to return
POPSTORE_FILOPNERR Unable to open the profile path file. See Section 14.2 for details.
POPSTORE_INSUFPRIV Process has insufficient privileges to access the user database.
POPSTORE_TOOLONG Length of specified group name is too long.
POPSTORE_VMERROR Insufficient virtual memory.

Previous Next Contents Index