Alert Functions
[The alert functions are not supported as of Windows Vista because the alerter and messenger services are not supported.]
The network management alert functions notify network service programs and applications of network events. An event is a particular instance of a process, occurrence, or state of hardware as defined by an application. The alert functions allow applications to indicate when predefined events occur. For Windows Server 2003: The alerter and messenger services are disabled by default on Windows Server 2003. You must re-enable the services before calling the network management Alert functions or the network management Message functions. The alert functions are listed following.
|
Function |
Description |
|
NetAlertRaise() |
Notifies all registered clients that a particular event has occurred. |
|
NetAlertRaiseEx() |
Simplifies notifying registered clients that a particular event has occurred, because, unlike NetAlertRaise(), NetAlertRaiseEx() does not require a STD_ALERT structure. |
The alerter service must be running on the client computer when you call the NetAlertRaise() function or the NetAlertRaiseEx() function. If the service is not running, the functions fail with ERROR_FILE_NOT_FOUND. The alerter service on the client calls the NetMessageBufferSend() function to send information to recipients. Applications, network services, and internal network components use the network management alert functions to raise an alert, notifying various applications or users when a particular type of event occurs. The alert category functions, data types, structures, and constants are defined in the LMCONS.H, LMERR.H, and LMALERT.H header files. To access these definitions, define the constants INCL_NETERRORS and INCL_NETALERT, and include the header file LM.H. The LMALERT.H file predefines the following alert classes (types of network events) for sending alerts:
You can define other classes of alerts for network applications as needed. For example, if an application on a server routinely writes large amounts of data to a disk drive, the application runs the risk of filling the disk. In this case, you might want to add the event no free disk space'' to trigger an alert that notifies the application to pause or to terminate the process that is filling the disk. The event name for an alert can be any text string. When you raise an alert with a call to the NetAlertRaise() function, the message data should consist of one STD_ALERT header structure, followed by additional fixed-length data that is alert-specific in one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure. Additional variable-length data can follow the alert-specific structure. (Calls to the NetAlertRaiseEx() function do not require a STD_ALERT structure.) The calling application must allocate the memory for all structures and variable-length data, and free the memory after the call returns. The following macros are available for use with alert data buffers.
|
Macro |
Description |
|
ALERT_OTHER_INFO |
Returns a pointer to the fixed-length data that follows the STD_ALERT structure in an alert message. |
|
ALERT_VAR_DATA |
Returns a pointer to the variable-length data that follows the alert-specific data in an alert message. |
Instead of using the network management alert functions, you may be able to use the Windows Management Instrumentation (WMI) SDK for event notification.
ApiBuffer Functions
The network management ApiBuffer functions are used to manage memory allocation used by an application with network management functions. However, in general, for other memory used by an application you should use the memory management functions instead of these ApiBuffer functions. The ApiBuffer functions are listed following.
|
Function |
Description |
|
NetApiBufferAllocate() |
Allocates memory from the heap. Call this function when you require compatibility with the NetApiBufferFree() function. |
|
NetApiBufferFree() |
Frees memory allocated by the NetApiBufferAllocate() function and other network management functions. |
|
NetApiBufferReallocate() |
Changes the size of a buffer allocated by a call to the NetApiBufferAllocate() function. |
|
NetApiBufferSize() |
Returns the size, in bytes, of a buffer allocated by a call to the NetApiBufferAllocate() function. |
For remotable functions that return information to the caller, the RPC run-time library allocates the buffer containing the return information. When the caller has finished processing the information, it must call the NetApiBufferFree() function to free the allocated buffer.
Directory Service Functions
The network management directory service functions allow developers to work with the domain controller and domain membership in the directory service. The network management directory service functions are listed following.
|
Function |
Description |
|
NetAddAlternateComputerName() |
Adds an alternate name for the specified computer. |
|
NetEnumerateComputerNames() |
Enumerates names for the specified computer. |
|
NetGetJoinableOUs() |
Retrieves a list of organizational units (OUs) in which a computer account can be created. |
|
NetGetJoinInformation() |
Retrieves join status information for the specified computer. |
|
NetJoinDomain() |
Joins a computer to a workgroup or domain. |
|
NetLogonSetServiceBits() |
Notifies the Netlogon service of the running state of the services on a domain controller. The caller must be running in the context of either the LocalSystem or the LocalService account. |
|
NetProvisionComputerAccount() |
Provisions a computer account for later used in an offline domain join operation. |
|
NetRemoveAlternateComputerName() |
Removes an alternate name for the specified computer. |
|
NetRenameMachineInDomain() |
Changes the name of a computer in a domain. |
|
NetSetPrimaryComputerName() |
Sets the primary computer name for the specified computer. |
|
NetUnjoinDomain() |
Unjoins a computer from a workgroup or a domain. |
|
NetValidateName() |
Verifies the validity of a computer name, workgroup name, or domain name. |