The Win32 Network Management APIs 11

 

 

 

 

 

Embedded Strings

 

Information structures will not contain embedded strings. This improves the alignment of the information structures and allows for OEM flexibility in the core functions. Any information field that is returned in an enumeration call that can be subsequently used as a key for the call to a GetInfo() network management function is guaranteed to be present in the enumeration buffer. If the variable-length information string that would specify the key field value will not fit, then the entire fixed-length structure for the entry is not returned. Other variable-length fields will be returned as a NULL pointer for the case in which the string does not fit.

 

Enumeration Resume Handles

 

Enumeration resume handles are identifiers for the actual resume key contained in the instance data for the function. This is required for security, interoperability, and to simplify the caller code for the function. If a NULL is passed for the pointer to the resume handle, no handle is stored and the enumeration search cannot be continued. This is useful in cases where the application does not want to enumerate all the items. If an error is returned from an enumeration call, the resume handle must be treated as invalid and not used for any subsequent enumeration calls. When this occurs you must restart the enumeration from the beginning.

 

Function Status

 

The network management functions return zero on success; a nonzero return code indicates an error. Because the network management functions use RPC, the error definitions include RPC error codes.

 

NLS Support

 

The network management functions take Unicode strings as input and provide Unicode strings on output. If your application generally works with ANSI strings, care must be taken to convert to and from Unicode where appropriate.

 

Parameter Error Reporting

 

The Add and SetInfo() network management functions return an index for a parameter that is in error. The caller may pass a NULL pointer for the parm_err parameter indicating that the field should not be set by the function.

 

RPC Buffer Allocation Errors

 

Because the RPC run-time library allocates memory for send and receive buffers, the function should expect RPC allocation errors. In the event of an RPC allocation error, a resumable handle is invalidated. This is a requirement because resumable functions are not rewindable.

 

Obsolete Information Fields

 

Many of the information fields in the core information structures will be obsolete. These fields will remain in the information structure for compatibility with 16-bit versions of Windows and will return an intelligent default on other Windows systems.

 

Using Network Management: Program Examples

 

The following section discusses how to use the network management functions in your application. The working program examples include:

 

  1. Looking up a user's full name
  2. Forcing a user to change the logon password
  3. Changing elements of user information
  4. Creating a new computer account
  5. Creating a local group and adding a user
  6. Looking up text for error code numbers
  7. And many more…

 

Looking Up a User's Full Name Program Example

 

Computers can be organized into a domain, which is a collection of computers network. The domain administrator maintains centralized user and group account information. To find the full name of a user, given the user name and domain name:

 

  1. Convert the user name and domain name to Unicode, if they are not already Unicode strings.
  2. Look up the computer name of the domain controller (DC) by calling NetGetDCName().
  3. Look up the user name on the DC computer by calling NetUserGetInfo().
  4. Convert the full user name to ANSI, unless the program is expecting to work with Unicode strings.

 

The following sample code is a function (GetFullName()) that takes a user name and a domain name in the first two arguments and returns the user's full name in the third argument.

Create a new empty Win32 console application project. Give the project name and change the project location is needed.

 

Looking Up a User's Full Name Program Example: Creating new Win32 console application project

 

Then, add the source file. Give it a name.

 

Looking Up a User's Full Name Program Example: Adding new C++ source code to the existing project

 

Then, add the following source code.

 

#include <windows.h>

#include <lm.h>

#include <stdio.h>

#pragma comment(lib, "netapi32.lib")

 

BOOL GetFullName(char *UserName, char *Domain, char *dest)

{

    WCHAR wszUserName[UNLEN+1]; // Unicode user name

    WCHAR wszDomain[256];

    LPBYTE ComputerName;

    NET_API_STATUS nStatus;

    // struct _SERVER_INFO_100 *si100; // Server structure

    // struct _USER_INFO_2 *ui; // User structure

    LPUSER_INFO_2 ui = NULL;

 

    // Convert ANSI user name and domain to Unicode

    MultiByteToWideChar(CP_ACP, 0, UserName, strlen(UserName)+1, wszUserName, sizeof(wszUserName)/sizeof(wszUserName[0]) );

    MultiByteToWideChar(CP_ACP, 0, Domain, strlen(Domain)+1, wszDomain, sizeof(wszDomain)/sizeof(wszDomain[0]));

 

    // Get the computer name of a DC for the domain.

    // The NULL means local computer

    nStatus = NetGetDCName(NULL, wszDomain, &ComputerName);

    if(nStatus == NERR_Success)

    {

        printf("NetGetDCName() is OK!\n");

    }

    else if (nStatus == NERR_DCNotFound)

    {

        printf("NetGetDCName() failed, DC cannot be found!\n");

        exit(1);

    }

    else if (nStatus == ERROR_BAD_NETPATH)

    {

        printf("NetGetDCName() failed, network path was not found!\n");

        exit(1);

    }

    else if (nStatus == ERROR_INVALID_NAME)

    {

        printf("server name is incorrect\n");

        exit(1);

    }

    else if (nStatus == ERROR_NOT_SUPPORTED)

    {

        printf("The request is not supported. !\n");

        exit(1);

    }

        nStatus = NetUserGetInfo((LPCWSTR)ComputerName, (LPCWSTR)&wszUserName, 2, (LPBYTE *)&ui);

        printf("NetUserGetInfo() returns %u\n", nStatus);

        // Look up the user on the DC.

        if (nStatus == NERR_Success)

        {

            if (ui != NULL)

            {

                // Convert the Unicode full name to ANSI.

                WideCharToMultiByte(CP_ACP, 0, ui->usri2_full_name, -1, dest, 256, NULL, NULL);

            }

        }

        else

        {

            printf("Error getting user information.\n");

            return(FALSE );

        }

        return (TRUE);

       }

 

int main(int argc, char **argv)

{

    char UserName[] = "";

    char Domain[] = "";

    char dest[] = "";

    if(argc != 3)

    {

        printf("Usage: %s [User_name] [Computer_name]\n", argv[0]);

        printf("Example: %s Kambing Utan\n", argv[0]);

        return 1;

    }

    GetFullName(UserName, Domain, dest);

    return 0;

}

 

Build and run the project. The following screenshot is a sample output.

           

Looking Up a User's Full Name Program Example: A sample output that should be run in the network based computer

 

 

 

 

< Win32 Network Management APIs 11 | Win32 Network Management APIs | Win32 Programming | Win32 Network Management APIs 12 >