<div class="content" name="NetrSessionEnum" uuid="02b1f559-fda2-4ba3-94c2-806eb2777183"><p>The NetrSessionEnum method MUST return information about
sessions that are established on a <a href="1709f6a7-efb8-4ded-b7ae-5cee9ee36320#gt_434b0234-e970-4e8c-bdfa-e16a30d96703" data-linktype="relative-path">server</a> or return an error
code.</p><dl>
<dd>
<div><pre> NET_API_STATUS NetrSessionEnum(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string, unique] WCHAR* ClientName,
   [in, string, unique] WCHAR* UserName,
   [in, out] PSESSION_ENUM_STRUCT InfoStruct,
   [in] DWORD PreferedMaximumLength,
   [out] DWORD* TotalEntries,
   [in, out, unique] DWORD* ResumeHandle
 );
</pre></div>
</dd></dl><p><b>ServerName: </b>An <a href="5f8329ee-1965-4ea1-ad35-3b29fbb63232" data-linktype="relative-path">SRVSVC_HANDLE (section 2.2.1.1)</a>
pointer that identifies the server. The <a href="1709f6a7-efb8-4ded-b7ae-5cee9ee36320#gt_60e0e1fa-66fe-41e1-b5e3-ceab97e53506" data-linktype="relative-path">client</a> MUST map this
structure to an RPC binding handle (see <a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a> sections 4.3.5
and 5.1.5.2). The server MUST ignore this parameter.</p><p><b>ClientName: </b>A pointer to a null-terminated
UTF-16 string that specifies the name of the computer session for which
information is to be returned. This string MUST be one of the following: a NULL
(zero-length) string; or a string that MUST begin with \\.</p><p><b>UserName: </b>A pointer to a null-terminated
UTF-16 string that specifies the user name for which information is to be
returned.</p><p><b>InfoStruct: </b>A pointer to a structure, in the
format of a <a href="e560d8c6-13e1-47b6-bde3-5377251ab5ff" data-linktype="relative-path">SESSION_ENUM_STRUCT</a>.
The SESSION_ENUM_STRUCT structure has a <b>Level</b> member that specifies the
type of structure to return. The <b>Level</b> member MUST be one of the values
specified in section 2.2.4.21.</p><p><b>PreferedMaximumLength: </b>Specifies the preferred
maximum length, in bytes, of the returned data. If the value that is specified
is <a href="789ec187-e01b-4da6-a7ff-9cb9e0857230" data-linktype="relative-path">MAX_PREFERRED_LENGTH</a>,
the method MUST attempt to return all entries.</p><p><b>TotalEntries: </b>The total number of entries that
could have been enumerated if the buffer had been big enough to hold all the
entries.</p><p><b>ResumeHandle: </b>A pointer to a value that
contains a handle that is used to continue an existing session search in <b>SessionList</b>,
as specified in section <a href="98c56700-5c9d-4246-b294-1357faa9ed57" data-linktype="relative-path">3.1.1.1</a>.
The handle MUST be zero on the first call and remain unchanged for subsequent
calls. If the <i>ResumeHandle</i> parameter is NULL, no resume handle MUST be
stored. If this parameter is not NULL and the method returns ERROR_MORE_DATA,
this parameter receives an implementation-specific nonzero value that can be
passed in subsequent calls to this method to continue with the enumeration.</p><dl>
<dd>
<p>If this parameter is NULL or points to 0x00000000,
the enumeration starts from the beginning of the <b>SessionList</b>.</p>
</dd></dl><p><b>Return Values: </b>The method returns 0x00000000
(NERR_Success) to indicate success; otherwise, it returns a nonzero error code.
The method can take any specific error code value, as specified in <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>
section <a href="../ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d" data-linktype="relative-path">2.2</a>.
The most common error codes are listed in the following table.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 NERR_Success</td>
  <td>The client request succeeded.</td>
 </tr><tr>
  <td>0x00000005 ERROR_ACCESS_DENIED</td>
  <td>Access is denied.</td>
 </tr><tr>
  <td>0x0000007C ERROR_INVALID_LEVEL</td>
  <td>The system call level is not correct.</td>
 </tr><tr>
  <td>0x00000057 ERROR_INVALID_PARAMETER</td>
  <td>The parameter is incorrect.</td>
 </tr><tr>
  <td>0x000000EA ERROR_MORE_DATA</td>
  <td>The client request succeeded. More entries are available. Not all entries could be returned in the buffer size that is specified by PreferedMaximumLength.</td>
 </tr><tr>
  <td>0x00000008 ERROR_NOT_ENOUGH_MEMORY</td>
  <td>Not enough storage is available to process this command.</td>
 </tr><tr>
  <td>0x00000908 NERR_ClientNameNotFound</td>
  <td>A session does not exist with the computer name.</td>
 </tr><tr>
  <td>0x0000092F NERR_InvalidComputer</td>
  <td>The computer name is not valid.</td>
 </tr><tr>
  <td>0x000008AD NERR_UserNotFound</td>
  <td>The user name could not be found.</td>
 </tr></tbody></table>
</dd></dl><p>In response to the NetrSessionEnum message, the server MUST
enumerate the <b>Session</b> entries in <b>SessionList</b> based on the value
of the <i>ResumeHandle</i> parameter. For each entry, the server MUST query
session properties by invoking the underlying server events as specified in <a href="../ms-cifs/d416ff7c-c536-406e-a951-4f04b2fd1d2b" data-linktype="relative-path">[MS-CIFS]</a>
section <a href="../ms-cifs/55355166-f9ce-4fba-9f31-983e1ae6bb7f" data-linktype="relative-path">3.3.4.14</a>
and <a href="../ms-smb2/5606ad47-5ee0-437a-817e-70c366052962" data-linktype="relative-path">[MS-SMB2]</a>
section <a href="../ms-smb2/0eb76132-1b0f-4b80-a228-8f31d401e7a5" data-linktype="relative-path">3.3.4.18</a>,
providing <i>Session.GlobalSessionId</i> as the input parameter. When the
server receives a STATUS SUCCESS for a Session.GlobalSessionId from either a
CIFS or SMB2 server, the server MUST consider the received SESSION_INFO_502
structure as valid, and it MUST continue to query all other sessions that are established
on the server. The server MUST then return information about some or all valid
sessions that are established on the server, depending on the qualifier
parameters that are specified.</p><p>The <i>ClientName</i> parameter specifies a qualifier for
the returned information. If a <i>ClientName</i> is specified (that is, it is
not a NULL (zero-length) string), the sesi502_cname field returned in the
SESSION_INFO_502 structure MUST match the <i>ClientName</i> for the session to
be returned.</p><p>If a <i>ClientName</i> is specified, it MUST start with
&#34;\\&#34;; otherwise, the server MUST fail the call with a
NERR_InvalidComputer error code. If a <i>ClientName</i> is specified and it
contains more than 1,024 characters, including the terminating null character,
the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.</p><p>The <i>UserName</i> parameter specifies a qualifier for the
returned information. If a <i>UserName</i> is specified (that is, not a NULL
(zero-length) string), the sesi502_username field returned in the
SESSION_INFO_502 structure MUST match the <i>UserName</i> parameter for the
session to be returned. If a <i>UserName</i> parameter is specified and the
length of the <i>UserName</i> string, including the terminating null character,
is greater than 1,024 characters, the server MUST fail the call with an
ERROR_INVALID_PARAMETER error code.</p><p>The server MUST return only those sessions that match all
specified qualifiers. If no entries that match the qualifiers
(ClientName/UserName) are found when a qualifier is specified, the server MUST
fail the call with either an NERR_UserNotFound or NERR_ClientNameNotFound error
code.</p><p>The <i>ClientName</i> and <i>UserName</i> parameters have no
role in determining the value of <i>ResumeHandle</i>. The server uses the <i>ResumeHandle</i>
parameter to start the enumeration (as described in the processing rules that
follow for the <i>ResumeHandle</i> parameter), and then applies these qualifier
parameters, if specified, to restrict the returned results to only those items
that pass the qualifier test (as described previously in this topic for <i>ResumeHandle</i>).</p><p>The <i>InfoStruct</i> parameter has a <b>Level</b> member
whose valid values are 0, 1, 2, 10, and 502. If the <b>Level</b> member is not
equal to one of the valid values, the server MUST fail the call with an
ERROR_INVALID_LEVEL error code.</p><p>The server MUST fill the return structures as follows.</p><p>If the <b>Level</b> member is 0, the server MUST return the
information about sessions by filling the <a href="008091bb-e34b-4d18-9718-855a10e5e9ba" data-linktype="relative-path">SESSION_INFO_0_CONTAINER</a>
structure in the <b>SessionInfo</b> field of the <i>InfoStruct</i> parameter as
follows. The SESSION_INFO_0_CONTAINER structure contains an array of <a href="de05e0e5-a988-4db0-8550-ade157457a04" data-linktype="relative-path">SESSION_INFO_0</a> structures.</p><ul><li><p><span><span> 
</span></span><b>sesi0_cname</b> MUST be set to <b>session.sesi502_cname</b>.</p>
</li></ul><p>If the <b>Level</b> member is 1, the server MUST return the
information about sessions by filling the <a href="f50dd0c2-db75-4fbe-9e14-c5a1cc31aa18" data-linktype="relative-path">SESSION_INFO_1_CONTAINER</a>
structure in the <b>SessionInfo</b> field of the <i>InfoStruct</i> parameter as
in the following. The SESSION_INFO_1_CONTAINER structure contains an array of <a href="73f86f62-aaf5-4cb2-8bcb-3bf2a4449966" data-linktype="relative-path">SESSION_INFO_1</a> structures.</p><ul><li><p><span><span> 
</span></span><b>sesi1_cname</b> MUST be set to <b>session.sesi502_cname</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi1_username</b> MUST be set to <b>session.sesi502_username</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi1_num_opens</b> MUST be set to <b>session.sesi502_num_opens</b>.</p>
</li></ul><p>If the <b>Level</b> member is 2, the server MUST return the
information about <b>sessions</b> by filling the <a href="382eb968-8fd5-46fd-a439-ddfc8ee653dd" data-linktype="relative-path">SESSION_INFO_2_CONTAINER</a>
structure in the <b>SessionInfo</b> field of the <i>InfoStruct</i> parameter as
in the following. The SESSION_INFO_2_CONTAINER structure contains an array of <a href="d54c4fe8-b395-41b9-b771-3f3c9eeee91c" data-linktype="relative-path">SESSION_INFO_2</a> structures.</p><ul><li><p><span><span> 
</span></span><b>sesi2_cname</b> MUST be set to <b>session.sesi502_cname</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_username</b> MUST be set to <b>session.sesi502_username</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_num_opens</b> MUST be set to <b>session.sesi502_num_opens</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_idle_time</b> MUST be set to <b>session.sesi502_idletime</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_time</b> MUST be set to <b>session.sesi502_time</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_user_flags</b> MUST be set to <b>session.sesi502_user_flags</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi2_cltype_name</b> MUST be set to <b>session.sesi502_cltype_name</b>.</p>
</li></ul><p>If the <b>Level</b> member is 10, the server MUST return the
information about <b>sessions</b> by filling the <a href="4cddb417-ad2c-4334-b488-ce6659bced18" data-linktype="relative-path">SESSION_INFO_10_CONTAINER</a>
structure in the <b>SessionInfo</b> field of the <i>InfoStruct</i> parameter as
in the following. The SESSION_INFO_10_CONTAINER structure contains an array of <a href="65471e2f-f849-442f-aa0f-3747bcda4c9d" data-linktype="relative-path">SESSION_INFO_10</a>
structures.</p><ul><li><p><span><span> 
</span></span><b>sesi10_cname</b> MUST be set to <b>session.sesi502_cname</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi10_username</b> MUST be set to <b>session.sesi502_username</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi10_idle_time</b> MUST be set to <b>session.sesi502_idletime</b>.</p>
</li><li><p><span><span> 
</span></span><b>sesi10_time</b> MUST be set to <b>session.sesi502_time</b>.</p>
</li></ul><p>If the <b>Level</b> member is 502, the server MUST return
the sessions in the <a href="baacdb89-11c4-4db9-bbcd-aef830c63d60" data-linktype="relative-path">SESSION_INFO_502</a>
structure by filling the <a href="2f95d8a6-1ce6-4338-ba7a-799f107059db" data-linktype="relative-path">SESSION_INFO_502_CONTAINER</a>
structure in the <b>SessionInfo</b> field of the <i>InfoStruct</i> parameter.
The SESSION_INFO_502_CONTAINER structure contains an array of SESSION_INFO_502
structures.</p><p>The <i>PreferedMaximumLength</i> parameter specifies the
maximum number of bytes that the server can return for the <b>SessionInfo</b>
buffer. If <i>PreferedMaximumLength</i> is insufficient to hold all the
entries, the server MUST return the maximum number of entries that will fit in
the <b>SessionInfo</b> buffer and return ERROR_MORE_DATA. If this parameter is
equal to MAX_PREFERRED_LENGTH, the server MUST return all the requested data.</p><p>If the server returns NERR_Success or ERROR_MORE_DATA, it
MUST set the <i>TotalEntries</i> parameter to equal the total number of entries
that exceed the qualifier filter (<i>ClientName</i> or <i>UserName</i> as
previously described) and that could have been enumerated from the current
resume position.</p><p>If the <i>PreferedMaximumLength</i> is insufficient to hold
all the entries and if the client has specified a <i>ResumeHandle</i>, the
server MUST set <i>ResumeHandle</i> to some implementation-specific value that
allows the server to continue with this enumeration on a subsequent call to
this method with the same value for <i>ResumeHandle</i>.</p><p>The following rules specify processing of the <i>ResumeHandle</i>
parameter:</p><ul><li><p><span><span> 
</span></span>If the <i>ResumeHandle</i> parameter is either NULL or points to
0x00000000, the enumeration MUST start from the beginning of the <b>SessionList</b>.</p>
</li><li><p><span><span> 
</span></span>If the <i>ResumeHandle</i> parameter points to a nonzero value,
the server must validate the <i>ResumeHandle</i>.</p>
<ul><li><p><span><span>  </span></span>If
the value of <i>ResumeHandle</i> is less than the size of the <b>SessionList</b>,
the server MUST continue enumeration based on the value of <i>ResumeHandle</i>.
The value of <i>ResumeHandle</i> specifies the index into the <b>SessionList</b>
after which enumeration is to begin.</p>
</li><li><p><span><span>  </span></span>If
the value of <i>ResumeHandle</i> is greater than or equal to the size of the <b>SessionList</b>,
the server MUST return NERR_Success and zero entries.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the client specified a <i>ResumeHandle</i> and the server
returns ERROR_MORE_DATA (0x000000EA), the server MUST set <i>ResumeHandle</i>
to the index value of the last enumerated session in the <b>SessionList</b>.</p>
</li></ul><p>Because the <i>ResumeHandle</i> specifies the index into the
list and the list of active sessions can be modified between multiple requests,
the results of a query spanning multiple requests using the <i>ResumeHandle</i>
can be unreliable, offering either duplicate or inactive sessions.</p><p>The server SHOULD<a id="Appendix_A_Target_52"></a><a aria-label="Product behavior note 52" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_52" data-linktype="relative-path">&lt;52&gt;</a> enforce
the security measures to verify that the caller has the required permissions to
execute this routine. If the caller does not have the required credentials, the
server SHOULD<a id="Appendix_A_Target_53"></a><a aria-label="Product behavior note 53" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_53" data-linktype="relative-path">&lt;53&gt;</a> fail the call.</p></div>