3.1.4.9 NetrShareEnumSticky (Opnum 36)

The NetrShareEnumSticky method retrieves information about each sticky shared resource whose IsPersistent setting is set in a ShareList.

 NET_API_STATUS NetrShareEnumSticky(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, out] LPSHARE_ENUM_STRUCT InfoStruct,
   [in] DWORD PreferedMaximumLength,
   [out] DWORD* TotalEntries,
   [in, out, unique] DWORD* ResumeHandle
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). If this parameter is NULL, the local computer is used.

InfoStruct: A pointer to a structure, in the format of a SHARE_ENUM_STRUCT (section 2.2.4.38). The SHARE_ENUM_STRUCT structure has a Level member that specifies the type of structure to return in the ShareInfo member. The Level member MUST be set to one of the values specified in section 2.2.4.38 (excluding SHARE_INFO_501_CONTAINER).

PreferedMaximumLength: Specifies the preferred maximum length, in bytes, of the returned data. If the specified value is MAX_PREFERRED_LENGTH, the method MUST attempt to return all entries.

TotalEntries: The total number of entries that could have been enumerated if the buffer had been big enough to hold all the entries.

ResumeHandle: A pointer to a value that contains a handle, which is used to continue an existing connection search. The handle MUST be zero on the first call and remain unchanged for subsequent calls. If the ResumeHandle parameter is NULL, a resume handle MUST NOT 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.

If this parameter is NULL or points to 0x00000000, the enumeration starts from the beginning of the list of the currently active connections.

Return Values: 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 [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code

Description

0x00000000

NERR_Success

The client request succeeded.

0x000000EA

ERROR_MORE_DATA

The client request succeeded. More entries are available. Not all entries could be returned in the buffer size that is specified by PreferedMaximumLength.

0x0000084B

NERR_BufTooSmall

The client request succeeded. More entries are available. The buffer size that is specified by PreferedMaximumLength was too small to fit even a single entry.

In response to a NetrShareEnumSticky message, the server MUST enumerate all the sticky shares in the ShareList whose IsPersistent setting is set, or return an error code. If the server is restarted, any shares that are created before the restart that are not sticky MUST be forgotten. Information about sticky shares MUST be stored in a persistent store,<59> and the shares MUST be restored (that is, re-created on the server) after the server is restarted.

The NetrShareEnumSticky method MUST NOT support Level 501 and MUST enumerate only sticky shares. Other than this difference, the server MUST process this message in exactly the same manner as the NetrShareEnum message.