3.2.4.2 NetrWkstaSetInfo (Opnum 1)

  • Article

The NetrWkstaSetInfo method configures a remote computer according to the information structure passed in the call.

 unsigned long NetrWkstaSetInfo(
   [in, string, unique] WKSSVC_IDENTIFY_HANDLE ServerName,
   [in] unsigned long Level,
   [in, switch_is(Level)] LPWKSTA_INFO WkstaInfo,
   [in, out, unique] unsigned long* ErrorParameter
 );

ServerName: A WKSSVC_IDENTIFY_HANDLE structure (section 2.2.2.1) that identifies the server (2). The client MUST map this structure to an RPC binding handle ([C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

Level: The information level of the data. This parameter SHOULD be one of the following values.

Value

Meaning

0x000001F6

The WkstaInfo parameter points to a WKSTA_INFO_502 structure (section 2.2.5.4).

0x000003F5

The WkstaInfo parameter points to a WKSTA_INFO_1013 structure (section 2.2.5.5).

0x000003FA

The WkstaInfo parameter points to a WKSTA_INFO_1018 structure (section 2.2.5.6).

0x00000416

The WkstaInfo parameter points to a WKSTA_INFO_1046 structure (section 2.2.5.7).

WkstaInfo: A pointer to a buffer that specifies the data. The format of this data depends on the value of the Level parameter.

ErrorParameter: A pointer to a value that receives an unsigned 32-bit integer. This parameter is meaningful only if the method returns ERROR_INVALID_PARAMETER and Level is equal to one of the values in the preceding table.

The ErrorParameter value corresponds to the member of the WKSTA_INFO structure (section 2.2.4.1) specified by the WkstaInfo parameter, which caused the ERROR_INVALID_PARAMETER error.

Return Values: When the message processing result meets the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_INVALID_PARAMETER

0x00000057

One of the function parameters is not valid.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

If the Level parameter value is not valid, the server MUST fail the call as follows.

Note  All value ranges are inclusive.

Invalid level value

Failure processing

0x00000000--0x000001F5,

0x000001F7--0x000003F4,

0x000003F6--0x000003F9,

0x000003FB--0x00000415

0x00000417--0xFFFFFFFF

The server SHOULD return ERROR_INVALID_LEVEL.<31>

Otherwise, if the Level parameter equals 0x000001F6, the server MUST store values from the WKSTA_INFO_502 structure WkstaInfo502 member (section 2.2.4.1) specified by the WkstaInfo parameter into elements of the ADM (section 3.2.1) as follows:

  • wki502_keep_conn stored in Keep_Connection

  • wki502_max_cmds stored in Max_Commands

  • wki502_sess_timeout stored in Session_TimeOut

  • wki502_dormant_file_limit stored in DormantFileLimit

If the Level parameter equals 0x000003F5, the server MUST store values from the WKSTA_INFO_1013 structure WkstaInfo1013 member (section 2.2.4.1) of the WkstaInfo parameter into elements of the ADM, as follows:

  • wki1013_keep_conn stored in Keep_Connection.

If the Level parameter equals 0x000003FA, the server MUST store values from the WKSTA_INFO_1018 structure WkstaInfo1018 member (section 2.2.4.1) of the WkstaInfo parameter into elements of the ADM, as follows:

  • wki1018_sess_timeout stored in Session_TimeOut.

If the Level parameter equals 0x00000416, the server MUST store values from the WKSTA_INFO_1046 structure WkstaInfo1046 member (section 2.2.4.1) of the WkstaInfo parameter into elements of the ADM, as follows:

  • wki1046_dormant_file_limit stored in DormantFileLimit.

The server MUST validate the values stored from members of WKSTA_INFO structures specified by the WkstaInfo parameter. If this validation fails, a value SHOULD be returned in the ErrorParameter parameter according to the following table.<32>

For Level value 0x000001F6:

Member

Valid Range

ErrorParameter Value Returned

wki502_char_wait

This field is not used. The sender SHOULD initialize it to any value between 0-65535. The receiver SHOULD ignore this field.

0x0000000A

wki502_collection_time

This field is not used. The sender SHOULD initialize it to any value between 0-65535000. The receiver SHOULD ignore this field.

0x0000000B

wki502_maximum_collection_count

This field is not used. The sender SHOULD initialize it to any value between 0-65535. The receiver SHOULD ignore this field.

0x0000000C

wki502_keep_conn

1 - 65535

0x0000000D

wki502_max_cmds

50 - 65535

0x00000000

wki502_sess_timeout

60 - 65535

0x00000012

wki502_siz_char_buf

This field is not used. The sender SHOULD initialize it to any value between 64-4096. The receiver SHOULD ignore this field.

0x00000017

wki502_max_threads

This field is not used. The sender SHOULD initialize it to any value between 1-256. The receiver SHOULD ignore this field.

0x00000021

wki502_lock_quota

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x00000029

wki502_lock_increment

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x0000002A

wki502_lock_maximum

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x0000002B

wki502_pipe_increment

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x0000002C

wki502_pipe_maximum

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x0000002D

wki502_cache_file_timeout

0 - 0xFFFFFFFF

0x0000002F

wki502_dormant_file_limit

1 - 0xFFFFFFFF

0x0000002E

wki502_read_ahead_throughput

This field is not used. The sender SHOULD initialize it to any value between 0-0xFFFFFFFF. The receiver SHOULD ignore this field.

0x0000003E

wki502_num_mailslot_buffers

This field is not used. The sender MAY initialize it to any value. The receiver SHOULD ignore this field.

Not in use.

wki502_num_srv_announce_buffers

This field is not used. The sender MAY initialize it to any value. The receiver SHOULD ignore this field.

Not in use.

wki502_max_illegal_datagram_events

This field is not used. The sender MAY initialize it to any value. The receiver SHOULD ignore this field.

Not in use.

wki502_illegal_datagram_event_reset_frequency

This field is not used. The sender MAY initialize it to any value. The receiver SHOULD ignore this field.

Not in use.

wki502_log_election_packets

This field is not used. The sender MAY initialize it to any value. The receiver SHOULD ignore this field.

Not in use.

wki502_use_opportunistic_locking

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000030

wki502_use_unlock_behind

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000031

wki502_use_close_behind

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000032

wki502_buf_named_pipes

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000033

wki502_use_lock_read_unlock

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000034

wki502_utilize_nt_caching

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000035

wki502_use_raw_read

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000036

wki502_use_raw_write

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000037

wki502_use_write_raw_data

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000038

wki502_use_encryption

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x00000039

wki502_buf_files_deny_write

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x0000003A

wki502_buf_read_only_files

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x0000003B

wki502_force_core_create_mode

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x0000003C

wki502_use_512_byte_max_transfer

This field is not used. The sender SHOULD initialize it to 0. The receiver SHOULD ignore this field.

0x0000003D

For Level value 0x000003F5

Member

Valid Range

ErrorParameter Value Returned

wki1013_keep_conn

1-65535

0x0000000D

For Level value 0x000003FA:

Member

Valid Range

ErrorParameter Value Returned

wki1018_sess_timeout

60-65535

0x00000012

For Level value 0x00000416:

Member

Valid Range

ErrorParameter Value Returned

wki1046_dormant_file_limit

1-0xFFFFFFFF

0x0000002E

The server SHOULD<33> enforce security measures to verify that the caller has the required permissions to execute this routine. If the server enforces security measures, and the caller does not have the required credentials, the server MUST fail the call with ERROR_ACCESS_DENIED. Specifications for determining the identity of the caller for the purpose of performing an access check are in [MS-RPCE] section 3.3.3.1.3.