|< Windows Registry Tutorial 4 | Main | Windows Share Programming 2 >| Site Index | Download |


 

 

 

 

MODULE Q

WINDOWS OS

.:: SHARE:  STORY AND PROGRAM EXAMPLES::.

PART 1

 

 

 

 

What do we have in this Module?

  1. Network Management Functions

  2. Windows Share Functions

  3. Program Examples

  4. NetShareAdd()

  5. Parameters

  6. Program Example

  7. NetShareSetInfo()

  8. Parameters

  9. Remarks

  10. Program Example

My Training Period: xx hours. Before you begin, read some instruction here.

 

 

 

 

 

 

 

 

 

 

 

 

The expected abilities are:

Network Management Functions

 

 

Windows Share Functions

 

The network management share functions control shared resources. A shared resource is a local resource on a server (for example, a disk directory, print device, or named pipe) that can be accessed by users and applications on the network.

The share functions are listed following.

 

Function

Description

NetShareAdd()

Shares a resource on a server.

NetShareCheck()

Queries whether a server is sharing a device.

NetShareDel()

Deletes a share name from a server's list of shared resources.

NetShareEnum()

Retrieves share information about each shared resource on a server.

NetShareGetInfo()

Retrieves information about a specified shared resource on a server.

NetShareSetInfo()

Sets a shared resource's parameters.

 

Table 1.

 

The NetShareAdd() function allows a user or application to share a resource of a specific type using the specified share name.  The NetShareAdd() function requires the share name and local device name to share the resource.  A user or application must have an account on the server to access the resource.

You can also specify a security descriptor to be associated with a share.  Security descriptors specify which users are allowed to access files through the share, and with what type of access.  Specify a SECURITY_DESCRIPTOR with the SHARE_INFO_502 information level when calling NetShareAdd() or NetShareSetInfo().  On Windows 2000 and later, NetShareSetInfo() supports the SHARE_INFO_1501 information level  The network management functions use the following special share names for interprocess communication (IPC) and remote administration of the server:

  1. IPC$, reserved for interprocess communication.

  2. ADMIN$, reserved for remote administration.

  3. A$, B$, C$ (and other local disk names followed by a dollar sign), assigned to local disk devices.

To list all connections made to a shared resource on a server, or to list all connections established from a particular computer, call the NetConnectionEnum() function.

You can call NetConnectionEnum() at the CONNECTION_INFO_0 and CONNECTION_INFO_1 information levels. Share functions are available at the following information levels:

 

Structure

Description

SHARE_INFO_0

Structure contains the name of the shared resource.

SHARE_INFO_1

Structure contains information about the shared resource, including the name and type of the resource, and a comment associated with the resource.

SHARE_INFO_2

Structure contains information about the shared resource, including name of the resource, type and permissions, and the number of current connections.

SHARE_INFO_501

Structure contains information about the shared resource including the name and type of the resource, and a comment associated with the resource.

SHARE_INFO_502

Structure contains information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information.

SHARE_INFO_1005

Structure contains information about the shared resource.

 

Table 2.

 

The following information levels are valid only for NetShareSetInfo():

 

Structure

Description

SHARE_INFO_1004

Structure contains a comment associated with the shared resource.

SHARE_INFO_1006

Structure specifies the maximum number of concurrent connections that the shared resource can accommodate.

SHARE_INFO_1501

Structure contains the security descriptor associated with the specified share.

 

Table 3.

 

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 Windows 95/98/Me, the following information levels are supported on these platforms:

 

Structure

Description

connection_info_50

Structure contains the connection type, number of open files, connection time, and the number of users on the connection.

share_info_1

Structure contains information about the shared resource, including the name and type of the resource, and a comment associated with the resource.

share_info_50

Structure contains information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords.

 

Table 4.

 

By the way this Module will only discuss the Windows 2000 and above.

 

Program Examples

 

The following section will discussed the functions used for sharing Windows resources.  It starts with the function definition and then followed by a program example.  The application that used these functions is the Net share command as shown below.  You are encouraged to explore other functions and structures available in the share category or Network Management of MSDN.

 

C:\>net

The syntax of this command is:

 

NET [ ACCOUNTS | COMPUTER | CONFIG | CONTINUE | FILE | GROUP | HELP |

      HELPMSG | LOCALGROUP | NAME | PAUSE | PRINT | SEND | SESSION |

      SHARE | START | STATISTICS | STOP | TIME | USE | USER | VIEW ]

 

C:\>net share

 

Share name   Resource                        Remark

-------------------------------------------------------------------------------

E$           E:\                             Default share

IPC$                                         Remote IPC

D$           D:\                             Default share

I$           I:\                             Default share

G$           G:\                             Default share

F$           F:\                             Default share

ADMIN$       C:\WINDOWS                      Remote Admin

H$           H:\                             Default share

wwwroot$     c:\inetpub\wwwroot              Used for file share access to web

C$           C:\                             Default share

The command completed successfully.

 

C:\>net share ?

The syntax of this command is:

 

NET SHARE

sharename

          sharename=drive:path [/USERS:number | /UNLIMITED]

                               [/REMARK:"text"]

                               [/CACHE:Manual | Documents| Programs | None ]

          sharename [/USERS:number | /UNLIMITED]

                    [/REMARK:"text"]

                    [/CACHE:Manual | Documents | Programs | None]

          {sharename | devicename | drive:path} /DELETE

 

C:\>

 

NetShareAdd()

 

Item

Description

Function

NetShareAdd().

Use

To share a server resource.

Prototype

NET_API_STATUS NetShareAdd( LPWSTR servername, DWORD level, LPBYTE buf, LPDWORD parm_err);

Parameters

See below.

Return value

See below

Include file

<lm.h>

Remark

Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd() function.  The Print Operator can add printer shares.  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.

 

Table 5.

 

Parameters

 

servername - [in] Pointer to a string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used.  This parameter cannot specify the name of a computer that is running Windows Me, Windows 98, or Windows 95.  For Windows NT:  This string must begin with \\.

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

 

Value

Meaning

2

Specifies information about the shared resource, including name of the resource, type and permissions, and number of connections.  The buf parameter points to a SHARE_INFO_2 structure.

502

Specifies information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information.  The buf parameter points to a SHARE_INFO_502 structure.

 

 Table 6.

 

Windows Me/98/95:  The following level is valid.

 

Value

Meaning

50

Specifies 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.  Note that the string you specify in the shi50_path member must contain only uppercase characters.  If the path contains lowercase characters, calls to NetShareAdd() can fail with NERR_UnknownDevDir or ERROR_BAD_NET_NAME.

 

Table 7.

 

buf - [in] Pointer to the buffer that specifies the data.  The format of this data depends on the value of the level parameter.

parm_err - [out] Pointer to a value that receives the index of the first member of the share information structure that causes the ERROR_INVALID_PARAMETER error.  If this parameter is NULL, the index is not returned on error.

 

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.

 

Return code

Description

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_NAME

The character or file system name is invalid.

ERROR_INVALID_PARAMETER

The specified parameter is invalid.

NERR_DuplicateShare

The share name is already in use on this server.

NERR_RedirectedPath

The operation is invalid for a redirected resource. The specified device name is assigned to a shared resource.

NERR_UnknownDevDir

The device or directory does not exist.

 

Table 8.

 

Program Example

 

The following code sample demonstrates how to share a network resource using a call to the NetShareAdd() function.  The code sample fills in the members of the SHARE_INFO_2 structure and calls NetShareAdd(), specifying information level 2.  A password is not required if the platforms do not support share-level security.  The myfolder directory already created/available in the F: drive.

 

// Don't forget to add netapi32.lib to your project

// The return value of share functions code can be found in

// Network Management Error Codes in MSDN

// For Win Xp Pro, adjust accordingly for other Windows version

#define _WIN32_WINNT 0x0501

#define UNICODE

#include <windows.h>

#include <stdio.h>

#include <lm.h>

 

// Unicode main()...

int wmain(int argc, TCHAR *argv[ ])

{

   NET_API_STATUS res;

   SHARE_INFO_2 p;

   DWORD parm_err = 0;

   // Some prompt...

   if(argc < 5)

      printf("Usage: %ls <server_name> <share_name> <share_remark> <share_pass>\n", argv[0]);

   else

   {

      // Fill in the SHARE_INFO_2 structure.

      p.shi2_netname = LPWSTR(argv[2]);   

      p.shi2_type = STYPE_DISKTREE;     // disk drive including the directory...

      p.shi2_remark = LPWSTR(argv[3]);  // share remark

      p.shi2_permissions = ACCESS_ALL;  // all permission

      p.shi2_max_uses = -1;             // unlimited

      p.shi2_current_uses = 0;          // no current uses

      // Try finding a way to accept the share path through the command line...

      p.shi2_path = TEXT("F:\\myfolder"); // share path, here we want to share a folder

      p.shi2_passwd = argv[4];       // password

      // Call the NetShareAdd() function, specifying level 2.

      res = NetShareAdd(argv[1], 2, (LPBYTE) &p, &parm_err);

      // If the call succeeds, inform the user.

      if(res==0)

         printf("%ls share created successfully.\n", p.shi2_netname);

      // Otherwise, print an error, and identify the parameter in error.

      else

          printf("Failed to create %ls, error: %u parmerr = %u\n", p.shi2_netname, res, parm_err);

   }

   return 0;

}

 

A sample output:

F:\myproject\win32prog\Debug>addshare

Usage: addshare <server_name> <share_name> <share_remark> <share_pass>

 

F:\myproject\win32prog\Debug>addshare mypersonal mytestshare "Testing the NetShareAdd()" 1234

mytestshare share created successfully.

 

F:\myproject\win32prog\Debug>

 

Then verify our task through Windows explorer.

 

 

Figure 1: Our shared directory.

 

Also can be verified through Administrative Tools Computer Management MMC.

 

 

Figure 2: Viewing shared resources through Computer Management MMC.

 

Finally the directory property page.

 

 

Figure 3: Sharing property access from directory property page.

 

NetShareSetInfo()

 

Item

Description

Function

NetShareSetInfo().

Use

To set the parameters of a shared resource.

Prototype

NET_API_STATUS NetShareSetInfo( LPWSTR servername, LPWSTR netname, DWORD level, LPBYTE buf,

  LPDWORD parm_err);

Parameters

See below.

Return value

See below.

Include file

<lm.h>

Remark

-

 

Table 9.

 

Parameters

 

servername - [in] Pointer to a string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used.  For Windows NT, this string must begin with \\.

netname - [in] Pointer to a string that specifies the name of the share to set information on.

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

 

 

Value

Meaning

1

Specifies information about the shared resource, including the name and type of the resource, and a comment associated with the resource.  The buf parameter points to a SHARE_INFO_1 structure.

2

Specifies information about the shared resource, including name of the resource, type and permissions, password, and number of connections.  The buf parameter points to a SHARE_INFO_2 structure.

502

Specifies information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information.  The buf parameter points to a SHARE_INFO_502 structure.

1004

Specifies a comment associated with the shared resource.  The buf parameter points to a SHARE_INFO_1004 structure.

1005

Specifies a set of flags describing the shared resource.  The buf parameter points to a SHARE_INFO_1005 structure.

1006

Specifies the maximum number of concurrent connections that the shared resource can accommodate.  The buf parameter points to a SHARE_INFO_1006 structure.

1501

Specifies the SECURITY_DESCRIPTOR associated with the specified share. The buf parameter points to a SHARE_INFO_1501 structure.  For Windows NT:  This value is not supported.

 

Table 10.

 

Windows Me/98/95:  The following level is valid.

 

Value

Meaning

50

Specifies 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.  Note that the string you specify in the shi50_path member must contain only uppercase characters.  If the path contains lowercase characters, calls to NetShareSetInfo() can fail with NERR_UnknownDevDir or ERROR_BAD_NET_NAME.

 

Table 11

 

buf - [in] Pointer to the buffer that specifies the data.  The format of this data depends on the value of the level parameter.

parm_err - [out] Pointer to a value that receives the index of the first member of the share information structure that causes the ERROR_INVALID_PARAMETER error.  If this parameter is NULL, the index is not returned on error.

 

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.

 

Return code

Description

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.

NERR_NetNameNotFound

The share name does not exist.

 

Table 12

 

Some Remarks

 

Only members of the Administrators or Power Users local group, or those with Print or Server Operator group membership, can successfully execute the NetShareSetInfo() function.  The Print Operator can set information only about Printer shares. If the NetShareSetInfo() function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the share information structure that is invalid.  A share information structure begins with SHARE_INFO_ and its format is specified by the level parameter.  The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error.  The prefix shi*_ indicates that the member can begin with multiple prefixes, for example, shi2_ or shi502_.

 

Value

Member

SHARE_NETNAME_PARMNUM

shi*_netname

SHARE_TYPE_PARMNUM

shi*_type

SHARE_REMARK_PARMNUM

shi*_remark

SHARE_PERMISSIONS_PARMNUM

shi*_permissions

SHARE_MAX_USES_PARMNUM

shi*_max_uses

SHARE_CURRENT_USES_PARMNUM

shi*_current_uses

SHARE_PATH_PARMNUM

shi*_path

SHARE_PASSWD_PARMNUM

shi*_passwd

SHARE_FILE_SD_PARMNUM

shi*_security_descriptor

 

Table 13

 

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.

 

A Program Example

 

The following code sample demonstrates how to set the comment associated with a shared resource using a call to the NetShareSetInfo() function. To do this, the sample specifies information level 1004 (SHARE_INFO_1004).

 

// add the netapi32.lib...

// The return value of share functions code can be found in

// Network Management Error Codes in MSDN

// For Win Xp Pro, adjust accordingly for other Windows version

#define _WIN32_WINNT 0x0501

#define UNICODE

#include <windows.h>

#include <stdio.h>

#include <lm.h>

 

// accept 3 arguments...

int wmain(int argc, TCHAR *argv[])

{

   SHARE_INFO_1004 p;

   NET_API_STATUS res;

   DWORD parm_err = 0;

   if(argc < 4)

      printf("Usage: %ls <server_name> <share_name> <share \"remark\">\n", argv[0]);

   else

   {

      // Fill in SHARE_INFO_1004 structure member.

      p.shi1004_remark = argv[3];

      // Call the NetShareSetInfo() function, specifying information level 1004.

      res = NetShareSetInfo(argv[1], argv[2], 1004, (LPBYTE)&p, &parm_err);

      // Display the result of the call.

      if(res == 0)

         printf("Remark for the %ls share successfully set.\n", argv[2]);

      else

         printf("Cannot set the \"remark\", error: %u parmerr = %u\n", res, parm_err);

   }

   return 0;

}

 

A sample output:

F:\myproject\win32prog\Debug>setshare

Usage: setshare <server_name> <share_name> <share "remark">

 

F:\myproject\win32prog\Debug>setshare mypersonal mytestshare "This is new remark for the share"

Remark for the mytestshare share successfully set.

 

F:\myproject\win32prog\Debug>

 

Verify our task through the directory property page.

 

 

Figure 4: Our new remark for the previous share.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Further reading and digging:

 

  1. Check the best selling C, C++ and Windows books at Amazon.com.

  2. Microsoft Visual C++, online MSDN.

  3. MSDN library.

  4. For Multibytes, Unicode characters and Localization please refer to Locale, wide characters & Unicode (Story) and Windows users & groups programming tutorials (Implementation).

  5. Structure, enum, union and typedef story can be found C/C++ struct, enum, union & typedef.

  6. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussed Windows programming notations.

  7. Windows data type information is in Windows data types used in Win32 programming.

 

 

 

 

 

 

 

|< Windows Registry Tutorial 4 | Main | Windows Share Programming 2 >| Site Index | Download |


2003-2010 © Tenouk. All rights reserved.