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:
- Looking up a user's full name
- Forcing a user to change the logon password
- Changing elements of user information
- Creating a new computer account
- Creating a local group and adding a user
- Looking up text for error code numbers
- 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:
- Convert the user name and domain name to Unicode, if they are not already Unicode strings.
- Look up the computer name of the domain controller (DC) by calling NetGetDCName().
- Look up the user name on the DC computer by calling NetUserGetInfo().
- 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.
Then, add the source file. Give it a name.
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.
< Win32 Network Management APIs 11 | Win32 Network Management APIs | Win32 Programming | Win32 Network Management APIs 12 >