|< 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 someinstruction here.

The expected abilities are:

• Able to understand and use functions to manipulate Windows share.

• Able to gather and understand the required information in order to use those functions.

Network Management Functions

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

The following information levels are valid only forNetShareSetInfo():

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:

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()

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.

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

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 theERROR_INVALID_PARAMETER error.  If this parameter isNULL, the index is not returned on error.

Return Values

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

// 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()

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.

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

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 theERROR_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.

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 theNetShareSetInfo() 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 withSHARE_INFO_ and its format is specified by the level parameter.  The following table lists the values that can be returned in theparm_err parameter and the corresponding structure member that is in error.  The prefixshi*_ indicates that the member can begin with multiple prefixes, for example,shi2_ orshi502_.

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.

AProgram Example

The following code sample demonstrates how to set the comment associated with a shared resource using a call to theNetShareSetInfo() 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 otherWindows 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 C references, online MSDN.

3. Microsoft Visual C++, online MSDN.

4. ReactOS - Windows binary compatible OS - C/C++ source code repository, Doxygen.

5. Linux Access Control Lists (ACL) info can be found atAccess Control Lists.

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

7. Structure, enum, union and typedef story can be foundC/C++ struct, enum, union & typedef.

8. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussedWindows programming notations.

9. Windows data type information is inWindows data types used in Win32 programming.

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

2003-2010 © Tenouk. All rights reserved.