Workstation Category

The functions in the Workstation category provide some client functionality to UNIX system processes

Function	Description
NetWkstaGetInfo	Returns information about a client’s configuration components.
NetWkstaSetUID2	Logs a user name on or off the network.

The functions in the Workstation category enable applications to perform the following tasks:

log a user onto or off of a workstation

execute a logon script (stored on a logon server) for a particular user name

get information about a client’s configuration

To log a user onto or off of the network and to execute a logon script for the user, an application calls the NetWkstaSetUID2 function.

The NetWkstaGetInfo function returns information about a client's configuration.

Note

The client’s domain name (wki0_langroup component in the wksta_info data structure) must not duplicate any computer name or user name on the network.

Giving a domain the name of a computer will cause startup problems. If the like-named computer is started first, no other computer in the domain will be able to start. Conversely, if any computer in the like-named domain is started, the computer going by the domain name will be unable to start.

For more information on domains, see the Advanced Server Concepts and Planning.

Workstation Category Data Structures

The NetWkstaGetInfo function in this category uses the workstation information data structure. NetWkstaSetUID2 uses the logon and logoff information data structures.

Workstation Information (level 0)

The NetWkstaGetInfo function accepts or returns data at a level 0 of detail, using the wksta_info data structure, as follows:

struct wksta_info_0 {

unsigned short wki0_reserved_1;

unsigned long wki0_reserved_2;

char * wki0_root;

char * wki0_computername;

char * wki0_username;

char * wki0_langroup;

unsigned char wki0_ver_major;

unsigned char wki0_ver_minor;

unsigned long wki0_reserved_3;

unsigned short wki0_charwait;

unsigned long wki0_chartime;

unsigned short wki0_charcount;

unsigned short wki0_reserved_4;

unsigned short wki0_reserved_5;

unsigned short wki0_keepconn;

unsigned short wki0_keepsearch;

unsigned short wki0_maxthreads;

unsigned short wki0_maxcmds;

unsigned short wki0_reserved6;

unsigned short wki0_numworkbuf;

unsigned short wki0_sizworkbuf;

unsigned short wki0_maxwrkcache;

unsigned short wki0_sesstimeout;

unsigned short wki0_sizerror;

unsigned short wki0_numalerts;

unsigned short wki0_numservices;

unsigned short wki0_errlogsz;

unsigned short wki0_printbuftime;

unsigned short wki0_numcharbuf;

unsigned short wki0_sizcharbuf;

char * wki0_logon_server;

char * wki0_wrkheuristics;

unsigned short wki0_mailslots;

};

Note

The only meaningful fields in this structure when NetWkstaGetInfo is used in Advanced Server are the following: wki0_root, wki0_computername, wki0_username, wki0_langroup, wki0_logon_server, wki0_errlogsz, wki0_rel_minor, and wki0_rel_major .

Within this structure, the following parameters are defined:

wki0_reserved_1, wki0_reserved_2, wki0_reserved_3, wki0_reserved_4, wki0_reserved_5, and wki0_reserved_6 are reserved and must be 0.

wki0_root points to an ASCIIZ string containing the path to the computer’s lanman directory.

wki0_computername points to an ASCIIZ string containing the computer name of the local computer.

wki0_username points to an ASCIIZ string that contains the name of the user who is logged on to the specified workstation.

wki0_langroup points to an ASCIIZ string containing the name of the domain to which the computer belongs.

wki0_ver_major specifies the major version number of the Advanced Server software running on the computer.

wki0_ver_minor specifies the minor version number of the Advanced Server software running on the computer.

wki0_charwait specifies how many seconds the computer will wait for a remote resource to become available.

wki0_chartime specifies how many milliseconds the computer will collect data before sending the data to a character device resource. The workstation waits the specified time or collects the number of characters specified by wki0_charcount, whichever comes first.

wki0_charcount specifies how many bytes of information the computer will collect before sending the data to a character device resource. The workstation collects the specified number of bytes or waits the time specified by wki0_chartime, whichever comes first.

Note

Remote character devices are not available in Advanced Server.

wki0_keepconn specifies how many seconds an inactive connection from the computer to a server’s resource will be maintained.

wki0_keepsearch tells how many seconds an inactive search will continue.

wki0_maxthreads specifies how many threads the computer can dedicate to the network.

wki0_maxcmds specifies how many simultaneous network device driver commands can be sent to the network.

wki0_numworkbuf specifies how many internal buffers the computer has.

wki0_sizworkbuf specifies the size (in bytes) of each internal buffer.

wki0_maxwrkcache specifies the maximum size (in bytes) of an internal cache buffer.

wki0_sesstimeout tells how many seconds are waited before disconnecting an inactive session between a client and a server.

wki0_sizerror specifies the size (in bytes) of an internal error buffer.

wki0_numalerts specifies the maximum number of clients that can receive alert messages.

Note

Each mailslot or semaphore registered by the NetAlertStart function is a different client. The Alerter service registers at least three clients when it begins to run. For more information on alerts, see the Alert Category.

wki0_numservices specifies how many services can be installed on the computer at any time. For more information on services, see Service Category.

wki0_errlogsz specifies the maximum size (in KBytes) of the client’s error log file.

wki0_printbuftime specifies how many seconds are waited before closing inactive compatibility-mode print jobs.

wki0_numcharbuf specifies how many character pipe buffers and device buffers the client can have.

wki0_sizcharbuf specifies the maximum size (in bytes) of a character pipe buffer and device buffer.

wki0_logon_server points to an ASCIIZ string specifying the name of the client’s Centralized Logon server. A NULL string indicates no logon servers are available.

If the string is \\*, any available logon server is queried. For more information on the logon process, see Advanced Server Concepts and Planning.

wki0_wrkheuristics points to an ASCIIZ string of flags used to control a clients operation.

wki0_mailslots specifies the maximum number of mailslots allowed.

Workstation Information (level 1)

The wksta_info_1 data structure includes the fields of the level 0 data structure (wksta_info_0) plus wki1_logon_domain, wki1_oth_domains, and wki1_numdgrambuf.

For more information, see Workstation Information (level 0). The wksta_info_1 structure can be used with the NetWkstaGetInfo function.

The wksta_info_1 data structure has the following format:

struct wksta_info_1 {

unsigned short wki1_reserved_1;

unsigned long wki1_reserved_2;

char * wki1_root;

char * wki1_computername;

char * wki1_username;

char * wki1_langroup;

unsigned char wki1_ver_major;

unsigned char wki1_ver_minor;

unsigned long wki1_reserved_3;

unsigned short wki1_charwait;

unsigned long wki1_chartime;

unsigned short wki1_charcount;

unsigned short wki1_reserved_4;

unsigned short wki1_reserved_5;

unsigned short wki1_keepconn;

unsigned short wki1_keepsearch;

unsigned short wki1_maxthreads;

unsigned short wki1_maxcmds;

unsigned short wki1_reserved_6;

unsigned short wki1_numworkbuf;

unsigned short wki1_sizworkbuf;

unsigned short wki1_maxwrkcache;

unsigned short wki1_sesstimeout;

unsigned short wki1_sizerror;

unsigned short wki1_numalerts;

unsigned short wki1_numservices;

unsigned short wki1_errlogsz;

unsigned short wki1_printbuftime;

unsigned short wki1_numcharbuf;

unsigned short wki1_sizcharbuf;

char * wki1_logon_server;

char * wki1_wkheuristics;

unsigned short wki1_mailslots;

char * wki1_logon_domain;

char * wki1_oth_domains;

unsigned short wki1_numdgrambuf;

};

Note

The only meaningful fields in this structure when NetWkstaGetInfo is used in Advanced Server are the following: wki0_root, wki0_computername, wki0_username, wki0_langroup, wki0_logon_server, wki0_errlogsz, wki0_rel_minor, wki0_rel_major, wki1_logon_domain and wki1_oth_domains.

Within this structure, the following parameters are defined:

wki1_reserved_1 through wki1_mailslots have the same definitions as the corresponding fields in the wksta_info_0 data structure. For a complete description, see Workstation Information (level 0).

wki1_logon_domain points to an ASCIIZ string that names the domain in which the user is logged on. When no user is logged on, this string is returned as NULL.

wki1_oth_domains points to an ASCIIZ string that lists all domains in which the computer is enlisted. When no user is logged on, this string is returned as NULL.

wki1_numdgrambuf specifies the number of buffers to allocate for receiving statgrams.

Workstation Information (level 10)

The wksta_info_10 data structure is provided for remote users who need certain information about a server but who do not have admin privilege. The wksta_info_10 structure can be used with NetWkstaGetInfo.

The wksta_info_10 data structure has the following format:

struct wksta_info_10 {

char * wki10_computername;

char * wki10_username;

char * wki10_langroup;

unsigned char wki10_ver_major;

unsigned char wki10_ver_minor;

unsigned long wki10_logon_domain;

unsigned short wki10_oth_domains;

};

Each variable has the same meaning as its corresponding field in the wksta_info_0 and wksta_info_1 structures.

The only meaningful fields when NetWkstaGetInfo is used in Advanced Server are the following: wki10_computername, wki10_username, wki10_langroup, wki10_rel_minor, wki10_rel_major, wki10_logon_domain, and wki10_oth_domains.

Logon Information (level 1)

The user_logon_info_1 and user_logoff_info_1 data structures are returned by the NetWkstaSetUID2 function.

The user_logon_info_1 data structure has the following format:

struct user_logon_info_1 {

unsigned short usrlog1_code;

char usrlog1_eff_name[UNLEN+1];

char usrlog1_pad_1;

unsigned short usrlog1_priv;

unsigned long usrlog1_auth_flags;

unsigned short usrlog1_num_logons;

unsigned short usrlog1_bad_pw_count;

unsigned long usrlog1_last_logon;

unsigned long usrlog1_last_logoff;

unsigned long usrlog1_logoff_time;

unsigned long usrlog1_kickoff_time;

long usrlog1_password_age;

unsigned long usrlog1_pw_can_change;

unsigned long usrlog1_pw_must_change;

char * usrlog1_computer;

char * usrlog1_domain;

char * usrlog1_script_path;

unsigned long usrlog1_reserved;

};

Within this structure, the following parameters are defined:

usrlog1_code specifies the logon code used in conjunction with the code returned by the API function. For a list of specific values, see the "Return Code" section of the NetWkstaSetUID2 description.

usrlog1_eff_name specifies the account to which the user was logged on. The constant LM20_UNLEN is defined in the netcons.h header file.

usrlog1_pad_1 aligns the next structure on a word boundary. The pad element should not be used to hold data.

usrlog1_priv specifies the user's privilege level. The following possible values are defined in the access.h header file:

Code	Value	Privilege
USER_PRIV_GUEST	0	Guest
USER_PRIV_USER	1	User
USER_PRIV_ADMIN	2	Admin

usrlog1_auth_flags specifies a bit map of account operator privileges. The bits are defined as follows:

Mask	Bit	Meaning
AF_OP_PRINT	0	Print Operator
AF_OP_COMM	1	Comm Operator
AF_OP_SERVER	2	Server Operator
AF_OP_ACCOUNTS	3	Accounts Operator

userlog1_num_logons specifies the number of times this user is logged on. A value of -1 means the number of logons is unknown.

userlog1_bad_pw_count specifies the number of incorrect passwords entered since the last successful logon.

userlog1_last_logon specifies the time when the user last logged on. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

userlog1_last_logoff specifies the time when the user last logged off. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

userlog1_logoff_time specifies the time when the user should log off. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of -1 means the user never has to log off.

userlog1_kickoff_time specifies the time when the user will be logged off by the system. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of -1 means the system will not log off the user.

userlog1_password_age specifies the time (in seconds) since the user password was changed.

userlog1_pw_can_change specifies the time when the user is allowed to change the password. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of -1 means the user can change the password.

userlog1_pw_must_change specifies the time when the user must change the password. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

userlog1_computer specifies the computer where the user is logged on.

userlog1_domain specifies the domain at which the user is logged on.

userlog1_script_path specifies the relative path to the user logon script.

userlog1_reserved reserved; the value is undefined. This element should not be used.

Logoff Information (level 1)

The user_logoff_info_1 data structure has the following format:

struct user_logof_info_1 {

unsigned short usrlogf1_code;

unsigned short usrlogf1_duration;

unsigned short usrlogf1_num_logons

};

Within this structure, the following parameters are defined:

usrlogf_code defines a logoff code that is used in conjunction with the value returned by the API function. For a list of specific values, see the "Return Codes" section of the NetWkstaSetUID2 description.

usrlogf1_duration specifies the number of seconds elapsed since the user logged on.

usrlogf1_num_logons specifies the number of times this user is logged on. A value of -1 means the number of logons is unknown.