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

---

 

MODULE Q

WINDOWS OS

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

PART 1

 

My Training Period:          hours

 

Note:

Program examples compiled using Visual C++ .Net (Visual studio .Net 2003) except whenever mentioned.  It is low-level programming and the .Net used is Unmanaged (/clr is not set: Project menu → your_project_name Properties… sub menu → Configuration Properties folder → General subfolder → Used Managed Extension setting set to No).  This also applied to other program examples in other Modules of tenouk.com Tutorial that mentioned “compiled using Visual C++ .Net”.  Other settings are default.  Machine’s OS is standalone Win Xp SP2 except whenever mentioned.  Beware the codes that span more than one line.  Program examples have been tested for Non Destructive Test :o).  All information recomposed for Win 2000 (NT5.0) above.

 

WARNING

 

Wrongly modified and run the program examples presented here might collapse your Windows machine or disturb its integrity.  So for your Windows machine safety, make sure you fulfill the following conditions:

 

1. Already read, understood and agreed to tenouk.com small disclaimer.
2. Must be familiar with Windows OSes mainly NT5 (Windows 2000 above).
3. Should be fluent in the following C topics: Function, Array, Pointer, String, Structure and Unicode/Wide character.
4. Then, the basic knowledge and skills of the Windows Access Control.
5. Do not mess up your system (Get a test machine! And run the program examples on the test machine).
6. Must understand what you are going to do with the Windows APIs.
7. Function, structure, enumeration, type and macros used in this Module have been dumped at enum, structure, functions etc.
8. Related and required information (if any) not available in no. 7 can be found at MSDN Online.

 

Abilities

 

▪         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

 

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:   ▪          IPC$, reserved for interprocess communication. ▪          ADMIN$, reserved for remote administration. ▪          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():

 

 

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

 

 

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;

}

 

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

 

 

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

 

 

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.

 

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;

}

 

 

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.

 

 

 

More examples in next Module...

 

------------www.tenouk.com-------------