Platform SDK: Network Management

NetShareGetInfo

The NetShareGetInfo function retrieves information about a particular shared resource on a server.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute the NetShareGetInfo function at level 2. No special group membership is required for level 0 or level 1 calls.

Windows NT/2000: The parameter order is as follows.

NET_API_STATUS NetShareGetInfo(
  LPWSTR servername,  
  LPWSTR netname,     
  DWORD level,        
  LPBYTE *bufptr      
);

Windows 95/98: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. If the length of the buffer is not large enough to hold all of the data, the function returns as much as will fit in the buffer. The function returns the total number of bytes of information available in the pcbTotalAvail parameter. The parameter list is as follows.

extern API_FUNCTION
 NetShareGetInfo(
  const char FAR * pszServer,        
  const char FAR * pszNetName,       
  short sLevel,                      
  char FAR * pbBuffer,               
  unsigned short  cbBuffer,          
  unsigned short FAR * pcbTotalAvail 
);

Parameters

servername

[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.

netname

[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the share for which to return information.

level

[in] Specifies the information level of the data. This parameter can be one of the following values.

Value	Meaning
0	Return the share name. Windows NT/2000: The bufptr parameter points to a SHARE_INFO_0 structure. Windows 95/98: The pbBuffer parameter points to a share_info_0 structure.
1	Return information about the shared resource, including the name and type of the resource, and a comment associated with the resource. Windows NT/2000: The bufptr parameter points to a SHARE_INFO_1 structure. Windows 95/98: The pbBuffer parameter points to a share_info_1 structure.
2	Return information about the shared resource, including name of the resource, type and permissions, password, and number of connections. Windows NT/2000: The bufptr parameter points to a SHARE_INFO_2 structure. Windows 95/98: The pbBuffer parameter points to a share_info_2 structure.
50	Windows 95/98: Return information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords. The pbBuffer parameter points to a share_info_50 structure.
501	Windows NT/2000: Return the name and type of the resource, and a comment associated with the resource. The bufptr parameter points to a SHARE_INFO_501 structure.
502	Windows NT/2000: Return information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information. The bufptr parameter points to a SHARE_INFO_502 structure.
1005	Windows NT/2000: Return a value that indicates whether the share is the root volume in a Dfs tree structure. The bufptr parameter points to a SHARE_INFO_1005 structure.

bufptr

[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98: The caller must allocate and deallocate this buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value	Meaning
ERROR_ACCESS_DENIED	The user does not have access to the requested information.
ERROR_INVALID_LEVEL	The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER	The specified parameter is invalid.
ERROR_MORE_DATA	More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY	Insufficient memory is available.
NERR_BufTooSmall	The supplied buffer is too small.
NERR_NetNameNotFound	The share name does not exist.

Remarks

Windows 95/98: See the NetShareGetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareGetInfo function.

Windows NT/2000: The following code sample demonstrates how to retrieve information about a particular shared resource using a call to the NetShareGetInfo function. The sample calls NetShareGetInfo, specifying information level 502 (SHARE_INFO_502). If the call succeeds, the code prints the retrieved data. The sample also calls the IsValidSecurityDescriptor function to validate the shi502_security_descriptor member. Finally, the sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL, lpszShare;
   //
   // Check command line arguments.
   //
   switch(argc)
   {
   case 3:
      lpszServer = lpszArgv[2];
   case 2:
      lpszShare = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareGetInfo sharename <servername>\n");
      return;
   }
   //
   // Call the NetShareGetInfo function, specifying level 502.
   //
   if((res = NetShareGetInfo (lpszServer,lpszShare,502,(LPBYTE *) &BufPtr)) == ERROR_SUCCESS)
   {
      //
      // Print the retrieved data.
      //
      printf("%S\t%S\t%u\n",BufPtr->shi502_netname, BufPtr->shi502_path, BufPtr->shi502_current_uses);
      //
      // Validate the value of the 
      //  shi502_security_descriptor member.
      //
      if (IsValidSecurityDescriptor(BufPtr->shi502_security_descriptor))
         printf("It has a valid Security Descriptor.\n");
      else
         printf("It does not have a valid Security Descriptor.\n");
      //
      // Free the allocated memory.
      //
      NetApiBufferFree(BufPtr);
   }
   else 
      printf("Error: %ld\n",res);
   return;
}

If you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same functionality you can achieve by calling the network management share functions. For more information, see IADsFileShare.

Requirements