The DLC Interface

The Data Link Control (DLC) interface is a special-purpose, nonroutable protocol. It is not used for communication between computers running Windows and Windows NT. DLC provides connectivity from a computer running Windows or Windows NT to IBM mainframes or printers that are connected directly to the network.

The DLC interface exposes an explicit set of commands that are issued through a structure known as the command control block (CCB). The system conveys the information in the command control block to the DLC protocol driver. The DLC protocol driver provides access to IEEE 802.2 class I and class II services. It also provides the interface to send and receive raw 802.5, 802.3, and Ethernet type network frames.

This overview discusses the following topics:

  • Command Control Block Addresses
  • DLC Commands
  • DLC Command Completion
  • Chaining DLC Commands
  • Buffer Management
  • DLC Enhancements
  • DLC Differences Between Windows NT and Windows 95

For more information on DLC, contact IBM and order the IBM Local Area Network Technical Reference: IEEE 802.2 and NETBIOS Application Programming Interfaces.


About the DLC Interface

On Windows NT, the DLC interface can be accessed from Win32-based applications and from 16-bit Windows-based applications. The 32-bit interface conforms largely to the CCB2 interface. The 16-bit interface conforms to the CCB1 interface. Windows 95 and Windows 98 do not support CCB1 or a 16-bit interface.


Command Control Block Addresses

All network addresses in the command control block, including Ethernet addresses, must be in noncanonical form. In this form, the bits of each byte appear in the reverse order from their representation on the network.

A network adapter is provided with a permanent, universally administered address. Additionally, an application can provide a temporary replacement for this address and a group address for the adapter.

Many commands require a station identifier. You can specify the direct station, a service access point (SAP), or a link station. The direct station is referred to by three station identifiers, which differ only in how they receive frames. The three station identifiers are as follows:

ID | Meaning
0 | Receives all frames not directed to other defined stations.
1 | Receives Media Access Control (MAC) frames.
2 | Receives non-MAC frames.


DLC Commands

DLC commands are issued through a command control blocks. To issue a DLC command, call the AcsLan function, which receives two pointers to LLC_CCB structures representing command control blocks. The LLC_CCB structure contains information about the command to perform, an optional event handle, and a pointer to a parameter table. The parameter table contains information required by the command. The format of the parameter table varies from command to command.

The DLC commands fall into three functional groups.

Direct Interface Commands

The direct interface enables you to perform control functions on an adapter. It also enables you to open and close an adapter, obtain the error status, and set addresses. The following are the direct interface commands:

LLC_DIR_CLOSE_ADAPTER
LLC_DIR_CLOSE_DIRECT
LLC_DIR_INITIALIZE
LLC_DIR_INTERRUPT
LLC_DIR_OPEN_ADAPTER
LLC_DIR_OPEN_DIRECT
LLC_DIR_READ_LOG
LLC_DIR_SET_EXCEPTION_FLAGS
LLC_DIR_SET_FUNCTIONAL_ADDRESS
LLC_DIR_SET_GROUP_ADDRESS
LLC_DIR_SET_MULTICAST_ADDRESS
LLC_DIR_STATUS
LLC_DIR_TIMER_CANCEL
LLC_DIR_TIMER_CANCEL_GROUP
LLC_DIR_TIMER_SET

DLC (IEEE 802.2) Interface Commands

The DLC interface provides an interface to the logical link control (LLC) sublayer of the DLC protocol. It offers both connectionless and connection-oriented services. The following are the DLC interface commands:

LLC_DLC_CLOSE_SAP
LLC_DLC_CLOSE_STATION
LLC_DLC_CONNECT_STATION
LLC_DLC_FLOW_CONTROL
LLC_DLC_MODIFY
LLC_DLC_OPEN_SAP
LLC_DLC_OPEN_STATION
LLC_DLC_REALLOCATE_STATIONS
LLC_DLC_RESET
LLC_DLC_SET_THRESHOLD
LLC_DLC_STATISTICS

Transmit and Receive Commands

Data is exchanged between applications on the network in frames using transmit and receive commands. The protocol driver moves the contents of the transmit buffer to the adapter's work space for transmission. The protocol driver receives frames from the network and moves them to the application's buffers. The following are the transmit and receive commands:

LLC_BUFFER_CREATE
LLC_BUFFER_FREE
LLC_BUFFER_GET
LLC_READ
LLC_READ_CANCEL
LLC_RECEIVE
LLC_RECEIVE_CANCEL
LLC_RECEIVE_MODIFY
LLC_TRANSMIT_DIR_FRAME
LLC_TRANSMIT_FRAMES
LLC_TRANSMIT_I_FRAME
LLC_TRANSMIT_TEST_CMD
LLC_TRANSMIT_UI_FRAME
LLC_TRANSMIT_XID_CMD
LLC_TRANSMIT_XID_RESP_FINAL
LLC_TRANSMIT_XID_RESP_NOT_FINAL


DLC Command Completion

When synchronizing thread execution with the completion of a command, you can check for command completion using any combination of the following three methods:

  • Set the ulCompletionFlag member of the LLC_CCB structure to a nonzero value and issue an LLC_READ command to read the command completion status.
  • Provide an event handle in the hCompletionEvent member. The protocol driver sets the event to the signaled state upon command completion to notify the application. Use one of the wait functions to monitor the event.
  • Poll the uchDlcStatus member.

    Windows NT: This method is unreliable and should not be used. The system can update the uchDlcStatus member before setting the other return values.


Chaining DLC Commands

To enhance the performance of the protocol driver, your application can issue multiple DLC commands with a single invocation of the protocol driver. This is known as chaining commands.

To issue multiple commands, set the pNext member of the LLC_CCB structure to the next LLC_CCB structure in the chain. All commands issued in this manner must specify the same adapter in the uchAdapterNumber member. If the chained commands do not specify the same adapter, the system performs the following steps:

  1. Stops processing the chained commands.
  2. Returns a pointer to the first unprocessed command control block in the ppBadCcb parameter of the AcsLan function.
  3. Sets the uchDlcStatus member of the first unprocessed command control block to LLC_STATUS_CHAINED_DIFFERENT_ADAPTERS.
  4. Sets the return value for AcsLan to ACSLAN_STATUS_CHAINED_CCB_IN_ERROR.

Note Do not chain commands that are dependent on the completion of other commands. For example, do not chain LLC_DLC_OPEN_SAP, LLC_DLC_OPEN_STATION, and LLC_DLC_CONNECT_STATION, because the last two commands are dependent on the completion of the first command.


Buffer Management

The buffer management provided in the Win32 DLC is different than the buffer management provided in other implementations. However, the buffer headers are as defined in the IBM DLC interface specification.

The Win32 DLC buffers are allocated from a single virtual memory block. The DLC driver defines the buffer segment sizes. For each frame the driver receives, it allocates a minimal combination of 256, 512, 1024, 2048, and 4096 buffer segments (at most, one of each size). This minimizes the amount of nonpaged memory needed for different buffer segment headers. It also allocates the minimal number of buffers for the received frame. Applications can request the fixed size buffers or an optimal number of buffers for a frame size.

The DLC buffer pools are dynamically expanded during LLC_READ, LLC_DLC_FLOW_CONTROL, and LLC_BUFFER_GET commands if the size of the free buffers is less than the specified minimum threshold size for the application. However, the system cannot increase the buffer pool beyond the application-specified maximum size.

An application can use its own buffers for transmitting data or send data directly from the buffer pool. Because the DLC driver locks all transmit buffers that are not in the buffer pool, you should avoid using a large number of small buffers for transmitting data.

To improve performance, use the following techniques:

  • Allocate buffers from the buffer pool. Copy data to these buffers from the user buffers.
  • The negotiated maximum frame size should fit into a single DLC buffer. For example, use 2048 or 4096 minus the size of the frame and buffer headers.
  • Receive several frames with the LLC_READ command.


DLC Enhancements

There are significant differences between the IBM DLC interface specification and the implementation of the Win32 DLC. These differences are as follows:

  • All 16-bit segment offsets in command control blocks have been replaced by 32-bit flat pointers.
  • The buffer pool is managed by the DLC driver. Applications can no longer define the segment size of the buffer pool or add new buffers to the pool. However, the application must always check the size field in the buffer header.
  • The members of the command control block that are specific to IBM Token-Ring hardware have been removed. These members are not available on Ethernet adapters.
  • Win32 events replace OS/2 semaphores as the mechanism used to signal the completion of asynchronous commands.
  • Global resources that were shared by all applications are now available to each application separately. These resources include functional addresses, group addresses, link stations, SAP stations, and direct stations.
  • Applications can define a 48-bit multicast address on Ethernet adapters using the LLC_DIR_SET_MULTICAST_ADDRESS command. This overwrites the 32-bit broadcast address set by the LLC_DIR_SET_GROUP_ADDRESS command.
  • Applications can send several frames from a DLC station with the LLC_TRANSMIT_FRAMES command.
  • Windows NT: The application identifier and application key members of the command control block are obsolete. They have been superseded by an optional security descriptor in the LLC_EXTENDED_ADAPTER_PARMS structure.


DLC Differences Between Windows NT and Windows 95

There are significant differences between the Win32 DLC implementation on Windows NT and the Win32 DLC implementation Windows 95 and Windows 98. These differences are as follows:

  • Windows NT provides extensions for security, multiple processors, and Unicode character strings. These are not supported by Windows 95 or Windows 98.
  • Windows 95 and Windows 98 support the application identifier member of the command control block in the uchReserved2 member. On Windows NT, this member and the application key member have been superseded by an optional security descriptor in the LLC_EXTENDED_ADAPTER_PARMS structure.
  • Windows 95 and Windows 98 support polling the uchDlcStatus member of the command control block to check for command completion. This method is unreliable on Windows NT, so an application that uses it successfully on Windows 95 or Windows 98 may fail on Windows NT.
  • Windows 95 and Windows 98 allow an application to issue an LLC_DIR_STATUS command before it issues an LLC_DIR_OPEN_ADAPTER command. Windows NT does not support this behavior.
  • Windows 95 and Windows 98 do not support multiple logical adapters.
  • Windows 95 and Windows 98 do not have direct station support that is global to all applications.


DLC Reference

The following functions and structures are used in DLC.


DLC Functions

The following function is used in DLC.

AcsLan


AcsLan

The AcsLan function communicates with IBM mainframes or network peripheral devices, such as printers connected directly to the network, by using the data link control (DLC) protocol. You can submit commands by filling in a command control block (CCB) structure, LLC_CCB, and then calling AcsLan.

Commands submitted through AcsLan can complete synchronously or asynchronously. The DLC driver, not the caller, determines how a command completes.

ACSLAN_STATUS AcsLan(
  PLLC_CCB pCcb,       // pointer to the command control block
  PLLC_CCB *ppBadCcb   // pointer to a pointer to an invalid CCB
);

Parameters

pCcb
Pointer to an LLC_CCB structure describing the command to be performed.
ppBadCcb
Pointer to a pointer to an LLC_CCB structure. Use this parameter when you chain DLC commands. If the parameter is not NULL on input, this pointer will receive a pointer to the first invalid LLC_CCB structure in the chain.

Return Values

The function returns an ACSLAN_STATUS value. ACSLAN_STATUS is an enumerated type. The following values are defined.

Value | Meaning
ACSLAN_STATUS_COMMAND_ACCEPTED | The command has been processed and passed to the DLC driver. Asynchronous commands may or may not be completed. Check the uchDlcStatus member in the LLC_CCB structure to determine whether the command succeeded.
ACSLAN_STATUS_INVALID_CCB_POINTER | A pointer in the LLC_CCB structure, or the parameter table is invalid.
ACSLAN_STATUS_CCB_IN_ERROR | A problem was detected with the LLC_CCB structure. Check the values in the structure and resubmit it.
ACSLAN_STATUS_CHAINED_CCB_IN_ERROR | A problem was detected with an LLC_CCB structure in a chain of LLC_CCB structures.
ACSLAN_STATUS_SYSTEM_ERROR | This value is not used.
ACSLAN_STATUS_SYSTEM_STATUS | This value is not used.
ACSLAN_STATUS_INVALID_COMMAND | The command in the uchDlcCommand member of the LLC_CCB structure is unrecognized.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.
Import Library: Use dlcapi.lib.

See Also

The DLC Interface Overview, DLC Functions, LLC_CCB


DLC Structures

The following structures are used in DLC.

CCB_PARMS
DLC_LINK_LOG
DLC_SAP_LOG
LLC_ADAPTER_LOG
LLC_ADAPTER_LOG_ETH
LLC_ADAPTER_LOG_TR
LLC_ADAPTER_OPEN_PARMS
LLC_BUFFER
LLC_BUFFER_CREATE_PARMS
LLC_BUFFER_FREE_PARMS
LLC_BUFFER_GET_PARMS
LLC_CCB
LLC_CONTIGUOUS_BUFFER
LLC_DIR_INITIALIZE_PARMS
LLC_DIR_MULTICAST_ADDRESS
LLC_DIR_OPEN_ADAPTER_PARMS
LLC_DIR_OPEN_DIRECT_PARMS
LLC_DIR_READ_LOG_BUFFER
LLC_DIR_READ_LOG_PARMS
LLC_DIR_SET_EFLAG_PARMS
LLC_DIR_STATUS_PARMS
LLC_DIRECT_LOG
LLC_DLC_CONNECT_PARMS
LLC_DLC_LOG_BUFFER
LLC_DLC_MODIFY_PARMS
LLC_DLC_OPEN_SAP_PARMS
LLC_DLC_OPEN_STATION_PARMS
LLC_DLC_PARMS
LLC_DLC_REALLOCATE_PARMS
LLC_DLC_SET_THRESHOLD_PARMS
LLC_DLC_STATISTICS_PARMS
LLC_EXTENDED_ADAPTER_PARMS
LLC_NEXT_BUFFER
LLC_NOT_CONTIGUOUS_BUFFER
LLC_READ_PARMS
LLC_RECEIVE_PARMS
LLC_TRANSMIT_PARMS
LLC_XMIT_BUFFER


CCB_PARMS

The CCB_PARMS union represents the DLC parameter table. You can present the parameter table as a pointer to a structure, two USHORT values, an array of four UCHAR values, or a single ULONG value. You pass a pointer to this structure to the AcsLan function, through the u member of the LLC_CCB structure.

typedef union {
    PLLC_PARMS pParameterTable;
    struct {
        USHORT usStationId;
        USHORT usParameter;
    } dlc;
    struct {
        USHORT usParameter0;
        USHORT usParameter1;
    } dir;
    UCHAR auchBuffer[4];
    ULONG ulParameter;
} CCB_PARMS;

Members

pParameterTable
Specifies a pointer to a structure in the LLC_PARMS union that represents the parameter table. The LLC_PARMS union represents all parameter table structures for DLC. The DLC command determines the particular structure to use, as shown in the following table.
Command | Parameter Table
LLC_BUFFER_CREATE | LLC_BUFFER_CREATE_PARMS
LLC_BUFFER_FREE | LLC_BUFFER_FREE_PARMS
LLC_BUFFER_GET | LLC_BUFFER_GET_PARMS
LLC_DIR_INITIALIZE | LLC_DIR_INITIALIZE_PARMS
LLC_DIR_OPEN_ADAPTER | LLC_DIR_OPEN_ADAPTER_PARMS
LLC_DIR_OPEN_DIRECT | LLC_DIR_OPEN_DIRECT_PARMS
LLC_DIR_READ_LOG | LLC_DIR_READ_LOG_PARMS
LLC_DIR_SET_EXCEPTION_FLAGS | LLC_DIR_SET_EFLAG_PARMS
LLC_DIR_SET_MULTICAST_ADDRESS | LLC_DIR_MULTICAST_ADDRESS
LLC_DIR_STATUS | LLC_DIR_STATUS_PARMS
LLC_DLC_CONNECT_STATION | LLC_DLC_CONNECT_PARMS
LLC_DLC_MODIFY | LLC_DLC_MODIFY_PARMS
LLC_DLC_OPEN_SAP | LLC_DLC_OPEN_SAP_PARMS
LLC_DLC_OPEN_STATION | LLC_DLC_OPEN_STATION_PARMS
LLC_DLC_REALLOCATE_STATIONS | LLC_DLC_REALLOCATE_PARMS
LLC_DLC_SET_THRESHOLD | LLC_DLC_SET_THRESHOLD_PARMS
LLC_DLC_STATISTICS | LLC_DLC_STATISTICS_PARMS
LLC_READ | LLC_READ_PARMS
LLC_RECEIVE | LLC_RECEIVE_PARMS
LLC_TRANSMIT_DIR_FRAME | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_I_FRAME | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_TEST_CMD | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_UI_FRAME | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_XID_CMD | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_XID_RESP_FINAL | LLC_TRANSMIT_PARMS
LLC_TRANSMIT_XID_RESP_NOT_FINAL | LLC_TRANSMIT_PARMS

usStationId
Specifies the station identifier.
usParameter
Specifies an optional parameter.
usParameter0
The first optional parameter.
usParameter1
The second optional parameter.
auchBuffer
Specifies a group or functional address.
ulParameter
Specifies the parameter table.

Remarks

The following table shows how the usStationId, usParameter, usParameter0, usParameter1, auchBuffer, and ulParameter members are used by the commands whose parameter tables are not represented by a unique LLC_PARMS structure.

Command | Parameter Table
LLC_DIR_SET_FUNCTIONAL_ADDRESS | usParameter0 and usParameter1 contain the address to be set or reset.
LLC_DIR_SET_GROUP_ADDRESS | usParameter0 contains the group address to be set.
LLC_DIR_TIMER_CANCEL | usParameter0 and usParameter1 contain the address of the timer to be canceled.
LLC_DIR_TIMER_CANCEL_GROUP | usParameter0 and usParameter1 contain the timer completion flag.
LLC_DIR_TIMER_SET | usParameter0 contains the timer value.
LLC_DLC_CLOSE_SAP | usStationId contains the station identifier of the SAP to be closed and usParameter receives the station identifier of any link station on the SAP that is not closed.
LLC_DLC_CLOSE_STATION | usStationId contains the station identifier of the station to be closed.
LLC_DLC_FLOW_CONTROL | usStationId contains the station identifier and usParameter specifies one of the following options: LLC_RESET_LOCAL_BUSY_USER LLC_RESET_LOCAL_BUSY_BUFFER LLC_SET_LOCAL_BUSY_USER
LLC_DLC_RESET | usStationId contains the station identifier of the station to be reset. A value of zero defines all SAPs and all link stations. A value of 0xnn00 defines SAP nn and all its link stations.
LLC_READ_CANCEL | ulParameter contains the address of the command control block of the read command to be canceled.
LLC_RECEIVE_CANCEL | usStationId contains the station identifier of the SAP or link station of a pending LLC_RECEIVE command that is to be canceled.
LLC_RECEIVE_MODIFY | usStationId contains the station identifier and usParameter specifies the length of the user data in the buffers.

Remarks

If an LLC_READ command is pending that requests notification of data to be received, the cancellation of the LLC_RECEIVE command does not affect the LLC_READ command. After the LLC_RECEIVE_CANCEL command completes, the pNext member of the LLC_CCB structure contains the address of the canceled LLC_RECEIVE command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_BUFFER_CREATE_PARMS, LLC_BUFFER_FREE_PARMS, LLC_BUFFER_GET_PARMS, LLC_CCB, LLC_DIR_INITIALIZE_PARMS, LLC_DIR_OPEN_ADAPTER_PARMS, LLC_DIR_OPEN_DIRECT_PARMS, LLC_DIR_READ_LOG_PARMS, LLC_DIR_SET_EFLAG_PARMS, LLC_DIR_MULTICAST_ADDRESS, LLC_DIR_STATUS_PARMS, LLC_DLC_CONNECT_PARMS, LLC_DLC_MODIFY_PARMS, LLC_DLC_OPEN_SAP_PARMS, LLC_DLC_OPEN_STATION_PARMS, LLC_DLC_REALLOCATE_PARMS, LLC_DLC_SET_THRESHOLD_PARMS, LLC_DLC_STATISTICS_PARMS, LLC_READ_PARMS, LLC_RECEIVE_PARMS, LLC_TRANSMIT_PARMS


DLC_LINK_LOG

The DLC_LINK_LOG structure represents the link log. Specify this structure in the LLC_DLC_LOG_BUFFER union.

typedef struct {
    USHORT cI_FramesTransmitted;
    USHORT cI_FramesReceived;
    UCHAR cI_FrameReceiveErrors;
    UCHAR cI_FrameTransmissionErrors;
    USHORT cT1_ExpirationCount;
    UCHAR uchLastCmdRespReceived;
    UCHAR uchLastCmdRespTransmitted;
    UCHAR uchPrimaryState;
    UCHAR uchSecondaryState;
    UCHAR uchSendStateVariable;
    UCHAR uchReceiveStateVariable;
    UCHAR uchLastNr;
    UCHAR cbLanHeader;
    UCHAR auchLanHeader[32];
} DLC_LINK_LOG, *PDLC_LINK_LOG;

Members

cI_FramesTransmitted
Number of I frames transmitted.
cI_FramesReceived
Number of I frames received.
cI_FrameReceiveErrors
Number of I frame receive errors.
cI_FrameTransmissionErrors
Number of I frame transmission errors.
cT1_ExpirationCount
Number of times T1 expired (other than in data-transfer mode).
uchLastCmdRespReceived
Last command or response received.
uchLastCmdRespTransmitted
Last command or response sent.
uchPrimaryState
Link primary state.
uchSecondaryState
Link secondary state.
uchSendVariableState
Send state variable.
uchReceiveStateVariable
Receive state variable.
uchLastNr
Last received NR.
cbLanHeader
Length of the network header used in station transmissions.
auchLanHeader
Network header used in station transmissions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DLC_LOG_BUFFER


DLC_SAP_LOG

The DLC_SAP_LOG structure represents the SAP log. Specify this structure in the LLC_DLC_LOG_BUFFER union.

typedef struct {
    ULONG cTransmittedFrames;
    ULONG cReceivedFrames;
    ULONG cDiscardedFrames;
    ULONG cDataLost;
    USHORT cBuffersAvailable;
} DLC_SAP_LOG, *PDLC_SAP_LOG;

Members

cTransmittedFrames
Number of frames transmitted.
cReceivedFrames
Number of frames received.
cDiscardedFrames
Number of frames discarded (there was no LLC_RECEIVE command).
cDataLost
Number of times data was lost. Inadequate SAP buffers can cause data loss.
cBuffersAvailable
Number of buffers available in the SAP buffer pool.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DLC_LOG_BUFFER


LLC_ADAPTER_LOG

The LLC_ADAPTER_LOG union represents the adapter log. Specify this structure in the LLC_DIR_READ_LOG_BUFFER structure.

typedef union {
    LLC_ADAPTER_LOG_TR Tr;
    LLC_ADAPTER_LOG_ETH Eth;
} LLC_ADAPTER_LOG, *PLLC_ADAPTER_LOG;

Members

Tr
Specifies the address of an LLC_ADAPTER_LOG_TR structure representing the adapter log for a Token-Ring network.
Eth
Specifies the address of an LLC_ADAPTER_LOG_ETH structure representing the adapter log for an Ethernet network.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_ADAPTER_LOG_ETH, LLC_ADAPTER_LOG_TR, LLC_DIR_READ_LOG_BUFFER


LLC_ADAPTER_LOG_ETH

The LLC_ADAPTER_LOG_ETH structure represents the adapter log for an ethernet network. Specify this structure in the LLC_ADAPTER_LOG structure.

typedef struct {
    UCHAR cCRC_Error;
    UCHAR uchReserved1;
    UCHAR cAlignmentError;
    UCHAR uchReserved2;
    UCHAR cTransmitError;
    UCHAR uchReserved3;
    UCHAR cCollisionError;
    UCHAR cReceiveCongestion;
    UCHAR uchReserved[6];
} LLC_ADAPTER_LOG_ETH, *PLLC_ADAPTER_LOG_ETH;

Members

cCRC_Error
CRC errors.
uchReserved1
Reserved.
cAlignmentError
Alignment errors.
uchReserved2
Reserved.
cTransmitError
Transmit errors.
uchReserved3
Reserved.
cCollisionError
Collision errors.
cReceiveCongestion
Receive congestion errors.
uchReserved
Reserved.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_ADAPTER_LOG


LLC_ADAPTER_LOG_TR

The LLC_ADAPTER_LOG_TR structure represents the adapter log for a Token-Ring network. Specify this structure in the LLC_ADAPTER_LOG structure.

typedef struct {
    UCHAR cLineError;
    UCHAR cInternalError;
    UCHAR cBurstError;
    UCHAR cAC_Error;
    UCHAR cAbortDelimiter;
    UCHAR uchReserved1;
    UCHAR cLostFrame;
    UCHAR cReceiveCongestion;
    UCHAR cFrameCopiedError;
    UCHAR cFrequencyError;
    UCHAR cTokenError;
    UCHAR uchReserved2;
    UCHAR uchReserved3;
    UCHAR uchReserved4;
} LLC_ADAPTER_LOG_TR, *PLLC_ADAPTER_LOG_TR;

Members

cLineError
Line error.
cInternalError
Internal error.
cBurstError
Burst error.
cAC_Error
A/C error.
cAbortDelimiter
Abort delimiter.
uchReserved1
Reserved.
cLostFrame
Lost frame.
cReceiveCongestion
Receive congestion.
cFrameCopiedError
Frame copied error.
cFrequencyError
Frequency error.
cTokenError
Token error.
uchReserved2
Reserved.
uchReserved3
Reserved.
uchReserved4
Reserved.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_ADAPTER_LOG


LLC_ADAPTER_OPEN_PARMS

The LLC_ADAPTER_OPEN_PARMS structure represents the open parameters for the LLC_DIR_OPEN_ADAPTER command. You pass a pointer to this structure in the LLC_DIR_OPEN_ADAPTER_PARMS structure.

typedef struct {
    USHORT usOpenErrorCode;
    USHORT usOpenOptions;
    UCHAR auchNodeAddress[6];
    UCHAR auchGroupAddress[4];
    UCHAR auchFunctionalAddress[4];
    USHORT usReserved1;
    USHORT usReserved2;
    USHORT usMaxFrameSize;
    USHORT usReserved3[4];
    USHORT usBringUps;
    USHORT InitWarnings;
    USHORT usReserved4[3];
} LLC_ADAPTER_OPEN_PARMS, *PLLC_ADAPTER_OPEN_PARMS;

Members

usOpenErrorCode
Indicates the result of the open adapter testing.
usOpenOptions
Specifies the open options for the adapter. This member is a 16-bit value. Setting the various bits enables different options, as described in the following table:
Bit | Description
15 | The adapter will not attach itself to the network. Instead, it causes all transmitted user data to be wrapped as received data.
14 | Disables hard errors.
13 | Disables soft errors.
12 | Passes, as direct interface data, all adapter-class MAC frames that are received but not supported by the adapter. Otherwise, these frames are ignored.
11 | Passes, as direct interface data, all attention MAC frames that are not the same as the last attention MAC frame received. Otherwise, these frames are ignored.
10 | Reserved; should be 0.
9 | Reserved; should be 0.
8 | Participates in monitor contention. Otherwise, this adapter does not participate.
7 | Passes, as direct interface data, the first beacon MAC frame and all subsequent beacon MAC frames that have a change in the source address or the beacon type.
6 | Reserved; should be 0.
5 | Prevents the adapter from becoming a monitor during the open process. This bit is implemented only in 16/4 adapters.
4 | Selects no early token releases for an adapter operating at 16 Mbps. Otherwise, use the early token release.
3 | Reserved; should be 0.
2 | Reserved; should be 0.
1 | Reserved; should be 0.
0 | Reserved; should be 0.

auchNodeAddress
Specifies the LAN address of the adapter.
auchGroupAddress
Specifies the group address for which the adapter will receive messages. If the value is zero, no group address is set.
auchFunctionalAddress
Specifies the functional address for which the adapter will receive messages. The most significant bit and the least significant bit are ignored by the adapter. If the value is zero, no functional address is set.
usReserved1
Reserved.
usReserved2
Reserved.
usMaxFrameSize
The maximum frame size defined in NDIS.
usReserved3
Reserved.
usBringUps
Indicates the result of adapter bring-up testing for IBM Token-Ring network adapters. This member is not used on the PC Network or on Ethernet.
InitWarnings
Indicates that a nonfatal error occurred during initialization of the protocol drivers. This member can be one of the following values.
Value | Meaning
0 | No errors detected during configuration parameter processing.
1 | No configuration parameters found.
2 | Errors detected during configuration parameter processing; default values were used.

usReserved4
Reserved.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DIR_OPEN_ADAPTER_PARMS


LLC_BUFFER

The LLC_BUFFER union represents the buffer for received data. Specify this structure in the LLC_RECEIVE_PARMS structure.

typedef union _LLC_BUFFER LLC_BUFFER, *PLLC_BUFFER;

union _LLC_BUFFER {

    PLLC_BUFFER pNext;

    LLC_NEXT_BUFFER Next;

    struct LlcNextBuffer {
        LLC_NEXT_BUFFER Header;
        UCHAR auchData[];
    } Buffer;

    LLC_NOT_CONTIGUOUS_BUFFER NotContiguous;

    struct {
        LLC_NOT_CONTIGUOUS_BUFFER Header;
        UCHAR auchData[];
    } NotCont;

    LLC_CONTIGUOUS_BUFFER Contiguous;

    struct {
        LLC_CONTIGUOUS_BUFFER Header;
        UCHAR auchData[];
    } Cont;

};

Members

pNext
Specifies the address of an LLC_BUFFER structure representing the next buffer.
Next
The LLC_NEXT_BUFFER structure representing the next buffer.
Header
The LLC_NEXT_BUFFER structure representing the header.
auchData
Specifies the address of the data.
NotContiguous
The LLC_NOT_CONTIGUOUS_BUFFER structure representing the next buffer.
Header
The LLC_NOT_CONTIGUOUS_BUFFER structure representing the header.
auchData
Specifies the address of the data.
Contiguous
The LLC_CONTIGUOUS_BUFFER structure representing the next buffer.
Header
The LLC_CONTIGUOUS_BUFFER structure representing the header.
auchData
Specifies the address of the data.

Remarks

Media Access Control (MAC) frames consist of a LAN header followed by a data field. Non-MAC frames consist of a LAN header, a DLC header, and a data field. The application provides the data in the data field. The DLC header varies depending on the frame type: frames used by Type 2 protocols have a 4-byte DLC header and frames used by Type 1 protocols have a 3-byte header. The frame type also determines what information the application provides and how it is provided, as shown in the following table.

Frame Type | Description
MAC Frames | The application provides the complete LAN header and the data field. The source address in the LAN header is overwritten with the address used by the adapter.
I-Frames | The application provides only the data. The information used to build the headers is provided by the LLC_DLC_OPEN_STATION and LLC_DLC_CONNECT_STATION commands.
Direct Frames | The application provides the LAN header and the data in its own buffers. It provides the information to build the headers with one of the LLC_TRANSMIT commands. The command overwrites the source address in the LAN header with the address used by the adapter.

When you use more than one buffer to receive a frame, the format for the first buffer is different from the format of the other buffers used to contain the frame.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_CONTIGUOUS_BUFFER, LLC_NEXT_BUFFER, LLC_NOT_CONTIGUOUS_BUFFER, LLC_RECEIVE_PARMS


LLC_BUFFER_CREATE_PARMS

The LLC_BUFFER_CREATE_PARMS structure is the DLC parameter table for the LLC_BUFFER_CREATE command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    HANDLE hBufferPool;
    PVOID pBuffer;
    ULONG cbBufferSize;
    ULONG cbMinimumSizeThreshold;
} LLC_BUFFER_CREATE_PARMS, *PLLC_BUFFER_CREATE_PARMS;

Members

hBufferPool
Handle to the created buffer pool.
pBuffer
Specifies the address of an application-supplied buffer. The buffer can be statically allocated or dynamically allocated from the heap. The minimum size requirement is 0x2000. The buffer manager allocates all DLC buffers from this virtual buffer. This buffer area must not be used for anything else.
cbBufferSize
The total size of the buffer, pBuffer, in bytes.
cbMinimumSizeThreshold
The minimum locked size. The buffer manager tries to keep at least this much free space in the buffer pool. This parameter should be large enough to hold all data received between two sequential LLC_READ commands.

Remarks

Win32 DLC supports one buffer pool per process. After you open an adapter using the LLC_DIR_OPEN_ADAPTER command, you must give the DLC driver a buffer pool by using the LLC_BUFFER_CREATE command.

You should carefully select the total and minimum buffer pool sizes, because the memory manager has a dynamic quota of available pages for each process. Your application may not run if it tries to allocate a buffer pool that is too large.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_BUFFER_FREE_PARMS

The LLC_BUFFER_FREE_PARMS structure is the DLC parameter table for the LLC_BUFFER_FREE command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usReserved1;
    USHORT cBuffersLeft;
    ULONG ulReserved;
    PLLC_XMIT_BUFFER pFirstBuffer;
} LLC_BUFFER_FREE_PARMS, *PLLC_BUFFER_FREE_PARMS;

Members

usReserved1
Reserved.
cBuffersLeft
The number of free buffer segments in the pool after the command completes.
ulReserved
Reserved.
pFirstBuffer
Specifies the address of an LLC_XMIT_BUFFER structure representing the first buffer to be added to the pool.

Remarks

The buffers to be freed must have been obtained using the LLC_BUFFER_GET command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_XMIT_BUFFER


LLC_BUFFER_GET_PARMS

The LLC_BUFFER_GET_PARMS structure is the DLC parameter table for the LLC_BUFFER_GET command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usReserved1;
    USHORT cBuffersLeft;
    USHORT cBuffersToGet;
    USHORT cbBufferSize;
    PLLC_XMIT_BUFFER pFirstBuffer;
} LLC_BUFFER_GET_PARMS, *PLLC_BUFFER_GET_PARMS;

Members

usReserved1
Reserved.
cBuffersLeft
The number of free buffer segments in the pool after the command completes.
cBuffersToGet
The number of buffers to get from the pool. If you specify zero, the buffer list returned can consists of segments of different sizes.
cbBufferSize
The size of the requested buffers. The system rounds this number to the next largest segment size (256, 512, 1024, 2048, or 4096).
pFirstBuffer
Specifies the address of an LLC_XMIT_BUFFER structure representing the first buffer obtained.

Remarks

If cBuffersToGet is zero and cbBufferSize is the size of the frame that is copied to the buffers, the system returns enough buffers to contain the whole frame, including its buffer headers. Then cBuffersLeft receives the size of free locked memory, in 256-byte blocks, or 65536 if the actual size is about 1 MB.

If the pool contains an inadequate number of buffers, the command fails with the status code LLC_STATUS_INADEQUATE_BUFFERS.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_XMIT_BUFFER


LLC_CCB

The LLC_CCB structure represents a command control block. You pass a pointer to this structure to the AcsLan function.

typedef struct _LLC_CCB {
    UCHAR uchAdapterNumber;
    UCHAR uchDlcCommand;
    UCHAR uchDlcStatus;
    UCHAR uchReserved1;
    struct _LLC_CCB *pNext;
    ULONG ulCompletionFlag;
    CCB_PARMS u;
    HANDLE hCompletionEvent;
    UCHAR uchReserved2;
    UCHAR uchReadFlag;
    USHORT usReserved3
} LLC_CCB, *PLLC_CCB;

Members

uchAdapterNumber
Specifies adapter number 0 or 1.
uchDlcCommand
Specifies the command code. The following command codes are supported.
Code | Meaning
LLC_BUFFER_CREATE | Creates a new DLC buffer pool and returns its handle. The application must open at least one adapter before it can create the buffer pool.
LLC_BUFFER_FREE | Returns one or more buffers to the adapter pool. The buffers must have been obtained with the LLC_BUFFER_GET command.
LLC_BUFFER_GET | Returns the requested buffers. You can retrieve several buffers of the same size or an optimal set of buffers for the specified frame size.
LLC_DIR_CLOSE_ADAPTER Closes the adapter logically, releasing its resources and canceling any pending commands. Open SAPs or link stations are reset before the completion of this command. Canceled commands return the error code LLC_STATUS_CANCELLED_BY_SYSTEM_ACTION. Functional address bits are reset.

The pNext member receives the address of a queue of CCBs terminated by this command.
LLC_DIR_CLOSE_DIRECT | Releases ownership of all direct stations. If you use an LLC_READ command to post this command, the system returns the buffers from the direct buffer pool in the parameter table.
LLC_DIR_INITIALIZE | Resets the network adapter, returns any pending commands, and releases buffer resources. For security reasons, the command resets the adapter physically only if it was not functioning normally when you issued the command.
LLC_DIR_INTERRUPT | This command does not do anything. No parameter table is required.
LLC_DIR_OPEN_ADAPTER | Prepares the protocol drivers for network communication. The adapter must be in a logically closed state for this command to succeed.
LLC_DIR_OPEN_DIRECT | Gives the application ownership of the direct station and enables it to receive frames using the LLC_RECEIVE command.
LLC_DIR_READ_LOG | Reads and resets the adapter logs. The system transfers the log data to the buffer in the parameter table.
LLC_DIR_SET_EXCEPTION_FLAGS | Defines user-notification flags so the system notifies the application of exception conditions.
LLC_DIR_SET_FUNCTIONAL_ADDRESS | Sets or resets the functional addresses for the adapter to receive messages.
LLC_DIR_SET_GROUP_ADDRESS | Sets or resets the group address for which the adapter will receive messages. Only one application can set a group address for a Token-Ring adapter. This command can fail if the Ethernet adapter does not have an available multicast address.
LLC_DIR_SET_MULTICAST_ADDRESS | Sets a 48-bit multicast address for the current DLC adapter context. The application must issue this command before it can receive multicasts. This command is supported only on Ethernet networks and is an alternative to the LLC_DIR_SET_GROUP_ADDRESS command. This command can fail if the Ethernet adapter does not have an available multicast address. A value of zero removes the previous multicast address.
LLC_DIR_STATUS | Reads the general status information. You can issue this command before the LLC_DIR_OPEN_ADAPTER command, but after the LLC_DIR_INITIALIZE command.
LLC_DIR_TIMER_CANCEL | Cancels a timer that was previously initiated by an LLC_DIR_TIMER_SET command.
LLC_DIR_TIMER_CANCEL_GROUP | Cancels a group of timer commands that were previously initiated by the LLC_DIR_TIMER_SET command.
LLC_DIR_TIMER_SET | Initiates a programmable timer to expire after a designated interval.
LLC_DLC_CLOSE_SAP | Closes a SAP. The SAP cannot close unless all link stations are closed.
LLC_DLC_CLOSE_STATION | Closes a link station.
LLC_DLC_CONNECT_STATION | Starts or completes a connection between the local and remote link stations. Both the local station and the remote station must issue the command to establish the connection.
LLC_DLC_FLOW_CONTROL | Controls the flow of data across a single link station on a SAP or across every link station on a SAP. You should issue this command immediately after a link station enters a local busy state. The driver clears the busy state when there are enough free buffers to receive more frames.
LLC_DLC_MODIFY | Modifies the work values of an open link station or the default values of a SAP.
LLC_DLC_OPEN_SAP | Activates a SAP and reserves a number of link stations for the SAP.
LLC_DLC_OPEN_STATION | Allocates resources for a link station.
LLC_DLC_REALLOCATE_STATIONS | Reallocates the number of link stations allocated to a SAP. When reducing the number of stations, the command returns the deallocated stations to the adapter pool. When increasing the number of stations, the command assigns new stations from the adapter pool.
LLC_DLC_RESET | Resets the SAPs and their associated link stations. Affected resources are freed, and pending commands are terminated.
LLC_DLC_SET_THRESHOLD | Sets a threshold for the SAP or direct station's buffer pool. The application is notified whenever the number of buffers in the pool falls below this threshold.
LLC_DLC_STATISTICS | Reads and optionally resets the DLC log. The log is transferred to the buffer indicated by the parameter table.
LLC_READ | Performs a read operation. The operation is complete when the system sets the uchDlcStatus member and the sets the hCompletionEvent event to the signaled state. The data and optional header begin at offset 64.
LLC_READ_CANCEL | Cancels a pending LLC_READ command for the application.
LLC_RECEIVE | Receives data. The command fails if the application has not created a buffer pool.
LLC_RECEIVE_CANCEL | Cancels a pending LLC_RECEIVE command.
LLC_RECEIVE_MODIFY | Receives data and puts some of it into a user buffer.
LLC_TRANSMIT_DIR_FRAME | Transmits data to the direct station.
LLC_TRANSMIT_I_FRAME | Transmits information data to a link station.
LLC_TRANSMIT_TEST_CMD | Requests the adapter to transmit a test command frame with the poll bit set. You can only use this command with a SAP.
LLC_TRANSMIT_UI_FRAME | Transmits unnumbered information data for a SAP. You can use this command only with a SAP.
LLC_TRANSMIT_XID_CMD | Transmits an XID command with the poll bit set on. You can use this command only with a SAP.
LLC_TRANSMIT_XID_RESP_FINAL | Transmits an XID response with the final bit on. You can only use this command with a SAP opened with SAP options specifying that the application will handle XID commands.
LLC_TRANSMIT_XID_RESP_NOT_FINAL | Transmits an XID response with the final bit off. You can only use this command with a SAP opened with SAP options specifying that the application will handle XID commands.

uchDlcStatus
Receives the command completion code. This value is set to LLC_STATUS_PENDING when the command is received. It is set to an appropriate code when the command is completed. For a list of the command completion codes, see the following Remarks section.
uchReserved1
Reserved.
pNext
Specifies the next command control block in the chain. Otherwise, set this parameter to NULL.
ulCompletionFlag
An optional flag set when an LLC_READ command is completed. If you set this parameter to zero before the command is issued, it is not used.
u
Specifies the address of a CCB_PARMS structure representing the parameter table.
hCompletionEvent
Specifies a handle to an event that you can use to check for command completion. Otherwise, set this parameter to zero. When the command is completed, it sets the event to the signaled state.
uchReserved2
Windows NT: Not used.

Windows 95 and Windows 98: The identifier of the application issuing the command. This value is returned by the LLC_DIR_OPEN_ADAPTER command and is used for all subsequent commands.

uchReadFlag
Specifies that an LLC_READ command control block is chained in this command. Otherwise, set this parameter to zero.
usReserved3
Reserved.

Remarks

The uchDlcStatus member receives an LLC_STATUS value representing the command completion code. LLC_STATUS is an enumerated type. The following completion codes are defined:

Code | Name
1 | LLC_STATUS_INVALID_COMMAND
2 | LLC_STATUS_DUPLICATE_COMMAND
3 | LLC_STATUS_ADAPTER_OPEN
4 | LLC_STATUS_ADAPTER_CLOSED
5 | LLC_STATUS_PARAMETER_MISSING
6 | LLC_STATUS_INVALID_OPTION
7 | LLC_STATUS_COMMAND_CANCELLED_FAILURE
10 | LLC_STATUS_CANCELLED_BY_USER
12 | LLC_STATUS_SUCCESS_NOT_OPEN
17 | LLC_STATUS_TIMER_ERROR
18 | LLC_STATUS_NO_MEMORY
21 | LLC_STATUS_LOST_LOG_DATA
22 | LLC_STATUS_BUFFER_SIZE_EXCEEDED
24 | LLC_STATUS_INVALID_BUFFER_LENGTH
25 | LLC_STATUS_INADEQUATE_BUFFERS
26 | LLC_STATUS_USER_LENGTH_TOO_LARGE
27 | LLC_STATUS_INVALID_PARAMETER_TABLE
28 | LLC_STATUS_INVALID_POINTER_IN_CCB
29 | LLC_STATUS_INVALID_ADAPTER
32 | LLC_STATUS_LOST_DATA_NO_BUFFERS
33 | LLC_STATUS_LOST_DATA_INADEQUATE_SPACE
34 | LLC_STATUS_TRANSMIT_ERROR_FS
35 | LLC_STATUS_TRANSMIT_ERROR
39 | LLC_STATUS_LINK_NOT_TRANSMITTING
40 | LLC_STATUS_INVALID_FRAME_LENGTH
50 | LLC_STATUS_INVALID_NODE_ADDRESS
51 | LLC_STATUS_INVALID_RCV_BUFFER_LENGTH
52 | LLC_STATUS_INVALID_XMIT_BUFFER_LENGTH
64 | LLC_STATUS_INVALID_STATION_ID
65 | LLC_STATUS_LINK_PROTOCOL_ERROR
66 | LLC_STATUS_PARMETERS_EXCEEDED_MAX
67 | LLC_STATUS_INVALID_SAP_VALUE
68 | LLC_STATUS_INVALID_ROUTING_INFO
71 | LLC_STATUS_LINK_STATIONS_OPEN
74 | LLC_STATUS_INCOMPATIBLE_COMMANDS
77 | LLC_STATUS_CONNECT_FAILED
79 | LLC_STATUS_INVALID_REMOTE_ADDRESS
80 | LLC_STATUS_CCB_POINTER_FIELD
87 | LLC_STATUS_INADEQUATE_LINKS
88 | LLC_STATUS_INVALID_PARAMETER_1
92 | LLC_STATUS_DIRECT_STATIONS_NOT_ASSIGNED
93 | LLC_STATUS_DEVICE_DRIVER_NOT_INSTALLED
94 | LLC_STATUS_ADAPTER_NOT_INSTALLED
95 | LLC_STATUS_CHAINED_DIFFERENT_ADAPTERS
96 | LLC_STATUS_INIT_COMMAND_STARTED
98 | LLC_STATUS_CANCELLED_BY_SYSTEM_ACTION
101 | LLC_STATUS_NO_GDT_SELECTORS
105 | LLC_STATUS_MEMORY_LOCK_FAILED
128 | LLC_STATUS_INVALID_BUFFER_ADDRESS
129 | LLC_STATUS_BUFFER_ALREADY_RELEASED
161 | LLC_STATUS_INVALID_VERSION
162 | LLC_STATUS_NT_ERROR_STATUS
255 | LLC_STATUS_PENDING

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_CONTIGUOUS_BUFFER

The LLC_CONTIGUOUS_BUFFER structure represents a buffer for received data. Specify this structure in the LLC_BUFFER structure.

typedef struct {
    PLLC_BUFFER pNextBuffer;
    USHORT cbFrame;
    USHORT cbBuffer;
    USHORT offUserData;
    USHORT cbUserData;
    USHORT usStationId;
    UCHAR uchOptions;
    UCHAR uchMsgType;
    USHORT cBuffersLeft;
    UCHAR uchRcvFS;
    UCHAR uchAdapterNumber;
    PLLC_BUFFER pNextFrame;
} LLC_CONTIGUOUS_BUFFER;

Members

pNextBuffer
Specifies the address of an LLC_BUFFER structure representing the next buffer in the frame.
cbFrame
Length of the entire frame.
cbBuffer
Length of this buffer.
offUserData
User data in this structure.
cbUserData
Length of user data.
usStationId
Station identifier.
uchOptions
Defines how the frame is received. Specify one of the following values.
Option | Description
LLC_CONTIGUOUS_MAC | The received data includes a LAN header.
LLC_CONTIGUOUS_DATA | The received data includes a LAN header and a DLC header.
LLC_NOT_CONTIGUOUS_DATA | The received data does not include the DLC header, but begins with the portion of the LAN frame that follows the DLC header.

uchMsgType
Specifies an LLC_FRAME_TYPES value representing the message type. LLC_FRAME_TYPES is an enumerated type. The following values are defined.
Value | Meaning
LLC_DIRECT_MAC | MAC frame (direct station on IBM Token-Ring network only).
LLC_I_FRAME | Information frame (link stations only).
LLC_UI_FRAME | UI frame.
LLC_XID_COMMAND_POLL | XID command (poll bit).
LLC_XID_COMMAND_NOT_POLL | XID command (not poll bit).
LLC_XID_RESPONSE_FINAL | XID response (final bit).
LLC_XID_RESPONSE_NO_FINAL | XID response (not final bit).
LLC_TEST_RESPONSE_FINAL | TEST response (final bit).
LLC_TEST_RESPONSE_NOT_FINAL | TEST response (not final bit).
LLC_DIRECT_8022 | 802.2 frame (direct station only).
LLC_DIRECT_ETHERNET_TYPE | Ethernet frame (direct station only).

cBuffersLeft
The number of basic buffer units left.
uchRcvFS
The received frame status.
uchAdapaterNumber
Adapter number.
pNextFrame
Specifies the address of an LLC_BUFFER structure representing the next frame.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_BUFFER


LLC_DIR_INITIALIZE_PARMS

The LLC_DIR_INITIALIZE_PARMS structure is the DLC parameter table for the LLC_DIR_INITIALIZE command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usBringUps;
    UCHAR Reserved[30];
} LLC_DIR_INITIALIZE_PARMS, *PLLC_DIR_INITIALIZE_PARMS;

Members

usBringUps
Indicates the result of adapter bring-up testing for IBM Token-Ring network adapters. This member is not used on the PC Network or on Ethernet.
Reserved
Information specific to MS-DOS or OS/2.

Remarks

This command initializes the protocol drivers, resets all adapter tables and buffers, and directs the adapter to run the bring-up tests (IBM Token-Ring network only). The adapter's programmable timer is started. All pending commands are returned to the application that issued them. When pending commands are returned, the error code received in the uchDlcStatus member of the LLC_CCB structure is LLC_STATUS_CANCELLED_BY_SYSTEM_ACTION.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DIR_SET_MULTICAST_ADDRESS

LLC_DIR_MULTICAST_ADDRESS

The LLC_DIR_MULTICAST_ADDRESS structure is the DLC parameter table for the LLC_DIR_SET_MULTICAST_ADDRESS command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    UCHAR auchMulticastAddress[6];
} LLC_DIR_MULTICAST_ADDRESS, *PLLC_DIR_MULTICAST_ADDRESS;

Members

auchMulticastAddress
The 48-bit multicast address.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DIR_OPEN_ADAPTER_PARMS

The LLC_DIR_OPEN_ADAPTER_PARMS structure is the DLC parameter table for the LLC_DIR_OPEN_ADAPTER command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    PLLC_ADAPTER_OPEN_PARMS pAdapterParms;
    PLLC_EXTENDED_ADAPTER_PARMS pExtendedParms;
    PLLC_DLC_PARMS pDlcParms;
    PVOID pReserved1;
} LLC_DIR_OPEN_ADAPTER_PARMS, *PLLC_DIR_OPEN_ADAPTER_PARMS;

Members

pAdapterParms
Specifies the address of an LLC_ADAPTER_OPEN_PARMS structure representing the open parameters.
pExtendedParms
Specifies the address of an LLC_EXTENDED_ADAPTER_PARMS structure representing the adapter parameter table.
pDlcParms
Specifies the address of an LLC_DLC_PARMS structure representing the DLC parameter table.
pReserved1
Reserved.

Remarks

This command prepares the protocol drivers for normal network communications on all network adapters for a given application. You must issue this command successfully before any network communication can start. The application cannot issue the command unless the adapter is in a logically closed state, which exists after one of the following occurs:

  • The adapter is initialized.
  • A fatal error has occurred.
  • The LLC_DIR_CLOSE_ADAPTER command has been executed.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_ADAPTER_OPEN_PARMS, LLC_DLC_PARMS LLC_EXTENDED_ADAPTER_PARMS


LLC_DIR_OPEN_DIRECT_PARMS

The LLC_DIR_OPEN_DIRECT_PARMS structure is the DLC parameter table for the LLC_DIR_OPEN_DIRECT command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT Reserved[4];
    USHORT usOpenOptions;
    USHORT usEthernetType;
    ULONG ulProtocolTypeMask;
    ULONG ulProtocolTypeMatch;
    USHORT usProtocolTypeOffset;
} LLC_DIR_OPEN_DIRECT_PARMS, *PLLC_DIR_OPEN_DIRECT_PARMS;

Members

Reserved
Reserved.
usOpenOptions
usEthernetType
Specifies an LLC_ETHERNET_TYPE value representing the type of Ethernet frame to receive. LLC_ETHERNET_TYPE is an enumerated type. The following values are defined.
Value | Meaning
LLC_ETHERNET_TYPE_DEFAULT | Use the parameter value set in the registry.
LLC_ETHERNET_TYPE_AUTO | Use automatic header type selection for links.
LLC_ETHERNET_TYPE_802_3 | Always use 802.3 LAN headers.
LLC_ETHERNET_TYPE_DIX | Always use LLC on DIX SNA type.

ulProtocolTypeMask
Specifies a mask used in a bitwise AND operation with the data. The result must be equal to ulProtocolTypeMatch. Otherwise, set this parameter to zero.
ulProtocolTypeMatch
Ignored if ulProtocolTypeMask is zero.
usProtocolTypeOffset
Specifies the distance of the protocol type from the beginning of the protocol header (offset 14 in the frame header). Ignored if ulProtocolTypeMask is zero.

Remarks

After you have issued the LLC_RECEIVE command for the direct station, the application has ownership of the direct station and can receive frames .

Win32 DLC differs from the IBM DLC specification in that you can receive frames of specific Ethernet types using the direct station when the usEthernetType member has a valid Ethernet type.

The ulProtoTypeMask, ulProtocolTypeMatch, and usProtocolTypeOffset members are optional. They specify the protocol type mask, match, and offset, respectively. They receive frames for a particular subprotocol type or socket. That is, the packet is received whenever the following statement is true:

(* (PULONG)((PUCHAR)pFrame + 14 + offset) & mask) == match

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DIR_READ_LOG_BUFFER

The LLC_DIR_READ_LOG_BUFFER union represents the log data returned by the LLC_DIR_READ_LOG command. The command returns either the adapter log, the direct interface log, or both logs. A pointer to this union is specified in the LLC_DIR_READ_LOG_PARMS structure.

typedef union {
    LLC_ADAPTER_LOG Adapter;
    LLC_DIRECT_LOG Dir;

    struct {
        LLC_ADAPTER_LOG Adapter;
        LLC_DIRECT_LOG Dir;
    } both;

} LLC_DIR_READ_LOG_BUFFER, *PLLC_DIR_READ_LOG_BUFFER;

Members

Adapter
Specifies the address of an LLC_ADAPTER_LOG structure representing the adapter log.
Dir
Specifies the address of an LLC_DIRECT_LOG structure representing the direct interface log.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_ADAPTER_LOG, LLC_DIR_READ_LOG_PARMS, LLC_DIRECT_LOG


LLC_DIR_READ_LOG_PARMS

The LLC_DIR_READ_LOG_PARMS structure is the DLC parameter table for the LLC_DIR_READ_LOG command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usTypeId;
    USHORT cbLogBuffer;
    PLLC_DIR_READ_LOG_BUFFER pLogBuffer;
    USHORT cbActualLength;
} LLC_DIR_READ_LOG_PARMS, *PLLC_DIR_READ_LOG_PARMS;

Members

usTypeId
Specifies the log to read. This member can be one of the following values.
Value | Meaning
LLC_DIR_READ_LOG_ADAPTER | Adapter error log.
LLC_DIR_READ_LOG_DIRECT | Direct interface error log.
LLC_DIR_READ_LOG_BOTH | Both the adapter and direct interface error logs.

cbLogBuffer
Size of the log buffer.
pLogBuffer
Specifies the address of an LLC_DIR_READ_LOG_BUFFER structure representing the log buffer.
cbActualLength
Receives the size of the log buffer.

Remarks

Not all network adapters support all members for this command. These members are supported by Microsoft-provided NDIS 3.0 drivers, including that for the IBM Token Ring.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_DIR_READ_LOG_BUFFER


LLC_DIR_SET_EFLAG_PARMS

The LLC_DIR_SET_EFLAG_PARMS structure is the DLC parameter table for the LLC_DIR_SET_EXCEPTION_FLAGS command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    ULONG ulAdapterCheckFlag;
    ULONG ulNetworkStatusFlag;
    ULONG ulPcErrorFlag;
    ULONG ulSystemActionFlag;
} LLC_DIR_SET_EFLAG_PARMS, *PLLC_DIR_SET_EFLAG_PARMS;

Members

ulAdapterCheckFlag
User notification flag for adapter-check exceptions. If this member is zero, the application will not be notified of these exceptions.
ulNetworkStatusFlag
User notification flag for network-status exceptions. If this member is zero, the application will not be notified of these exceptions.
ulPcErrorFlag
User notification flag for workstation errors. If this member is zero, the application will not be notified of these exceptions.
ulSystemActionFlag
User notification flag for system-action exceptions. If this member is zero, the application will not be notified of these exceptions.

Remarks

The flag members are used to request that information relating to exception events be passed to the application. You should issue this command immediately after issuing the LLC_DIR_OPEN_ADAPTER command if the application is to be notified of any exception conditions. Then issue an LLC_READ command, setting the hCompletionEvent member of the LLC_CCB structure. Whenever an exception occurs, this command will be executed and the event error code will be returned from the protocol driver.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DIR_STATUS_PARMS

The LLC_DIR_STATUS_PARMS structure is the DLC parameter table for the LLC_DIR_STATUS command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    UCHAR auchPermanentAddress[6];
    UCHAR auchNodeAddress[6];
    UCHAR auchGroupAddress[4];
    UCHAR auchFunctAddr[4];
    UCHAR uchMaxSap;
    UCHAR uchOpenSaps;
    UCHAR uchMaxStations;
    UCHAR uchOpenStation;
    UCHAR uchAvailStations;
    UCHAR uchAdapterConfig;
    UCHAR auchReserved1[10];
    ULONG ulReserved1;
    ULONG ulReserved2;
    ULONG ulMaxFrameLength;
    USHORT usLastNetworkStatus;
    USHORT usAdapterType;
} LLC_DIR_STATUS_PARMS, *PLLC_DIR_STATUS_PARMS;

Members

auchPermanentAddress
The permanent address encoded on the adapter.
auchNodeAddress
The adapter's network address, as set by the LLC_DIR_OPEN_ADAPTER command.
auchGroupAddress
The adapter's group address.
auchFunctAddr
The adapter's functional address.
uchMaxSap
The maximum number of SAPs allowed.
uchOpenSaps
The number of SAPs opened by LLC_DLC_OPEN_SAP commands.
uchMaxStations
The maximum number of link stations allowed, as set by the LLC_DIR_OPEN_ADAPTER command.
uchOpenStation
The number of stations opened with the LLC_DLC_OPEN_STATION or LLC_DLC_CONNECT_STATION command.
uchAvailStations
The number of available stations (those that the LLC_DLC_OPEN_SAP or LLC_DLC_REALLOCATE commands do not reserve).
uchAdapterConfig
The adapter configuration flags. This member is a 8-bit value. Setting the various bits enables different options, as described in the following table.
Bit | Description
7 CCB1: The original PC network adapter is present.
CCB2: Reserved.
6 | Reserved.
5 | CCB1: If set, the protocol driver returns the address of the extended status table at offset 50. If the extended status is not supported, the value at offset 50 is not changed.
4 | Token release. If not set, 16 Mbps adapters get early token release. If set, there is no early token release for adapters operating at 16 Mbps.
3-2 The amount, in kilobytes, of shared RAM.
00 = 8 KB
01 = 16 KB
10 = 32 KB
11 = 64 KB
1 | Reserved.
0 | Adapter data rate. If not set, the data rate is 4 Mbps. If set, the data rate is 16 Mbps.

auchReserved1
Reserved.
ulReserved1
Reserved.
ulReServed2
Reserved.
ulMaxFrameLength
Maximum frame length.
usLastNetworkStatus
Last network status.
usAdapterType
CCB2: The adapter type. This member can be one of the following values.
Value | Meaning
LLC_ADAPTER_ETHERNET | Ethernet adapter.
LLC_ADAPTER_TOKEN_RING | IBM Token-Ring network 16/4 adapter/A.

Remarks

This command can be issued before the LLC_DIR_OPEN_ADAPTER command, but after the LLC_DIR_INITIALIZE command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DIRECT_LOG

The LLC_DIRECT_LOG structure represents the direct interface log. Specify this structure in the LLC_DIR_READ_LOG_BUFFER structure.

typedef struct {
    ULONG cTransmittedFrames;
    ULONG cReceivedFrames;
    ULONG cDiscardedFrames;
    ULONG cDataLost;
    USHORT cBuffersAvailable;
} LLC_DIRECT_LOG, *PLLC_DIRECT_LOG;

Members

cTransmittedFrames
Number of frames transmitted.
cReceivedFrames
Number of frames received.
cDiscardedFrames
Number of frames discarded (there was no LLC_RECEIVE command).
cDataLost
Number of times data was lost.
cBuffersAvailable
Number of buffers available in the SAP buffer pool.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DIR_READ_LOG_BUFFER


LLC_DLC_CONNECT_PARMS

The LLC_DLC_CONNECT_PARMS structure is the DLC parameter table for the LLC_DLC_CONNECT_STATION command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    USHORT usReserved;
    PUCHAR pRoutingInfo;
} LLC_DLC_CONNECT_PARMS, *PLLC_DLC_CONNECT_PARMS;

Members

usStationId
The station identifier of the link station.
usReserved
Reserved.
pRoutingInfo
Specifies the address of the network routing information.

Remarks

If the remote partner for this link station is on a different ring, routing information is necessary for communication. If the link station was established due to the execution of an LLC_DLC_OPEN_STATION command, you must provide the routing information with this command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_LOG_BUFFER

The LLC_DLC_LOG_BUFFER union represents the log buffer. Specify this structure in the LLC_DLC_STATISTICS_PARMS structure.

typedef union {
    DLC_SAP_LOG Sap;
    DLC_LINK_LOG Link;
} LLC_DLC_LOG_BUFFER, *PLLC_DLC_LOG_BUFFER;

Members

Sap
Specifies the address of a DLC_SAP_LOG structure representing the SAP log.
Link
Specifies the address of a DLC_LINK_LOG structure representing the link log.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, DLC_LINK_LOG, DLC_SAP_LOG, LLC_DLC_STATISTICS_PARMS


LLC_DLC_MODIFY_PARMS

The LLC_DLC_MODIFY_PARMS structure is the DLC parameter table for the LLC_DLC_MODIFY command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usRes;
    USHORT usStationId;
    UCHAR uchT1;
    UCHAR uchT2;
    UCHAR uchTi;
    UCHAR uchMaxOut;
    UCHAR uchMaxIn;
    UCHAR uchMaxOutIncr;
    UCHAR uchMaxRetryCnt;
    UCHAR uchReserved1;
    USHORT usMaxInfoFieldLength;
    UCHAR uchAccessPriority;
    UCHAR auchReserved3[4];
    UCHAR cGroupCount;
    PUCHAR pGroupList;
} LLC_DLC_MODIFY_PARMS, *PLLC_DLC_MODIFY_PARMS;

Members

usRes
Reserved.
usStationId
SAP or link station identifier.
uchT1
Response timer. Valid values are 1 through 10. If the value is zero, the current value is used.
uchT2
Acknowledgment timer. If the value is zero, the current value is used.
uchTi
Inactivity timer. If the value is zero, the current value is used.
uchMaxOut
Maximum number of unacknowledged LLC_TRANSMIT commands. The limit for this value is 127. If the value is zero, the current value is used.
uchMaxIn
Maximum number of unacknowledged LLC_RECEIVE commands. The limit for this value is 127. If the value is zero, the current value is used.
uchMaxOutIncr
Dynamic window increment value. If the value is zero, the current value is used.
uchMaxRetryCnt
Maximum number of times an unacknowledged command can be retried. If the value is zero, the current value is used.
uchReserved1
Reserved.
usMaxInfoFieldLength
Maximum information field length. Only for link stations.
uchAccessPriority
Token-Ring access priority. This value is not recognized on other networks.
auchReserved3
Reserved.
cGroupCount
Number of group SAPs for this SAP. Valid values are 0 to 13.
pGroupList
Specifies the address of the group list. This member is ignored if cGroupCount is zero.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_OPEN_SAP_PARMS

The LLC_DLC_OPEN_SAP_PARMS structure is the DLC parameter table for the LLC_DLC_OPEN_SAP command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId
    USHORT usUserStatValue;
    UCHAR uchT1;
    UCHAR uchT2;
    UCHAR uchTi;
    UCHAR uchMaxOut;
    UCHAR uchMaxIn;
    UCHAR uchMaxOutIncr;
    UCHAR uchMaxRetryCnt;
    UCHAR uchMaxMembers;
    USHORT usMaxI_Field;
    UCHAR uchSapValue;
    UCHAR uchOptionsPriority;
    UCHAR uchcStationCount;
    UCHAR uchReserved2[2];
    UCHAR cGroupCount;
    PUCHAR pGroupList;
    ULONG DlcStatusFlags;
    UCHAR uchReserved3[8];
    UCHAR cLinkStationsAvail;
} LLC_DLC_OPEN_SAP_PARMS, *PLLC_DLC_OPEN_SAP_PARMS;

Members

usStationId
SAP or link station identifier.
usUserStatValue
Reserved for user.
uchT1
Response timer. If the value is zero, the default setting of 5 is used.
uchT2
Acknowledgment timer. If the value is zero, the default setting of 2 is used.
uchTi
Inactivity timer. If the value is zero, the default setting of 10 is used.
uchMaxOut
Maximum number of unacknowledged LLC_TRANSMIT commands. The limit for this value is 127. If the value is zero, the default setting of 2 is used.
uchMaxIn
Maximum number of unacknowledged LLC_RECEIVE commands. The limit for this value is 127. If the value is zero, the default setting of 1 is used.
uchMaxOutIncr
Dynamic window increment value.
uchMaxRetryCnt
Maximum number of retries for an unacknowledged command. The maximum valid value is 255. If the value is zero, the default setting of 8 is used.
uchMaxMembers
Maximum members for the group SAP.
usMaxI_Field
Maximum length of the information field. If the value is zero, the default setting of 600 is used.
uchSapValue
SAP value to be assigned.
uchOptionsPriority
SAP options and access priority. Specify one of the following options.
Option | Description
LLC_XID_HANDLING_IN_APPLICATION | The XID command frames for this SAP are passed to the application.
LLC_XID_HANDLING_IN_DLC | The XID command frames are handled for this SAP by the DLC function of the adapter.
LLC_INDIVIDUAL_SAP | The SAP is an individual SAP.
LLC_GROUP_SAP | The SAP is a group SAP.
LLC_MEMBER_OF_GROUP_SAP | The SAP may be a member of a group SAP.

uchcStationCount
Maximum number of link stations in the SAP. Provides resources for subsequent LLC_DLC_OPEN_STATION commands.
uchReserved2
Reserved.
cGroupCount
Number of group SAPs for this SAP. Valid values for the Token-Ring network are 0 through 8. Valid values for other networks are 0 through 255. If additional memberships are needed, use the LLC_DLC_MODIFY command.
pGroupList
Specifies the address of the group list. This member is ignored if cGroupCount is zero.
DlcStatusFlags
User notification flags for DLC status change.
uchReserved3
Reserved.
cLinkStationsAvail
Total number of available link stations.

Remarks

Opening an individual SAP requesting group SAP membership for a group SAP will fail if the membership is requested in group SAPs with different types. If this happens, the SAP opens with membership into the group SAPs specified until the SAP type of the group SAP listed changes. All subsequent group SAPs listed after a SAP type change has been detected will not be used for membership.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_OPEN_STATION_PARMS

The LLC_DLC_OPEN_STATION_PARMS structure is the DLC parameter table for the LLC_OPEN_STATION command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usSapStationId;
    USHORT usLinkStationId;
    UCHAR uchT1;
    UCHAR uchT2;
    UCHAR uchTi;
    UCHAR uchMaxOut;
    UCHAR uchMaxIn;
    UCHAR uchMaxOutIncr;
    UCHAR uchMaxRetryCnt;
    UCHAR uchRemoteSap;
    USHORT usMaxI_Field;
    UCHAR uchAccessPriority;
    PVOID pRemoteNodeAddress;
} LLC_DLC_OPEN_STATION_PARMS, *PLLC_DLC_OPEN_STATION_PARMS;

Members

usSapStationId
SAP station identifier.
usLinkStationId
Link station identifier.
uchT1
Response timer. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchT2
Acknowledgment timer. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchTi
Inactivity timer. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchMaxOut
Maximum number of unacknowledged LLC_TRANSMIT commands. The limit for this value is 127. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchMaxIn
Maximum number of unacknowledged LLC_RECEIVE commands. The limit for this value is 127. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchMaxOutIncr
Dynamic window increment value.
uchMaxRetryCnt
Maximum number of retries for an unacknowledged command. The limit for this value is 255. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchRemoteSap
Value of the remote SAP. It must be an individual SAP.
usMaxI_Field
Maximum information field length. If the value is zero, the default is as defined by the LLC_DLC_OPEN_SAP command.
uchAccessPriority
Token-ring access priority. This value is not recognized on other networks.
pRemoteNodeAddress
Specifies the destination address.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_PARMS

The LLC_DLC_PARMS structure represents the DLC parameter table for the LLC_DIR_OPEN_ADAPTER command. You pass a pointer to this structure in the LLC_DIR_OPEN_ADAPTER_PARMS structure.

typedef struct {
    UCHAR uchDlcMaxSaps;
    UCHAR uchDlcMaxStations;
    UCHAR uchDlcMaxGroupSaps;
    UCHAR uchDlcMaxGroupMembers;
    UCHAR uchT1_TickOne;
    UCHAR uchT2_TickOne;
    UCHAR uchTi_TickOne;
    UCHAR uchT1_TickTwo;
    UCHAR uchT2_TickTwo;
    UCHAR uchTi_TickTwo;
} LLC_DLC_PARMS, *PLLC_DLC_PARMS;

Members

uchDlcMaxSaps
The maximum number of SAPs that can be opened at one time. This value can be limited by available memory. Specify up to 126. If the value is zero, as the default setting of 2 is used.
uchDlcMaxStations
The maximum number of link stations that can be opened at one time. This value can be limited by available memory. Specify up to 255. If the value is zero, the default setting of 6 is used.
uchDlcMaxGroupSaps
The maximum number of group SAPs that can be opened at one time. Specify up to 125. If the value is zero, no group SAPs are allowed.
uchDlcMaxGroupMembers
The maximum number of SAPs that can be assigned to any given group. Specify up to 126.
uchT1_TickOne
The number of 40 millisecond intervals between timer ticks for the short DLC timer T1 (T1 timer values 1 through 5). If the value is zero, the default setting of 5 is used.
uchT2_TickOne
The number of 40 millisecond intervals between timer ticks for the short DLC timer T2 (T2 timer values 1 through 5). If the value is zero, the default setting of 1 is used.
uchTi_TickOne
The number of 40 millisecond intervals between timer ticks for the short DLC timer Ti (Ti timer values 1 through 5). If the value is zero, the default setting of 25 is used.
uchT1_TickTwo
The number of 40 millisecond intervals between timer ticks for the long DLC timer T1 (T1 timer values 6 through 10). If the value is zero, the default setting of 25 is used.
uchT2_TickTwo
The number of 40 millisecond intervals between timer ticks for the long DLC timer T2 (T2 timer values 6 through 10). If the value is zero, the default setting of 10 is used.
uchTi_TickTwo
The number of 40 millisecond intervals between timer ticks for the long DLC timer Ti (Ti timer values 6 through 10). If the value is zero, the default setting of 125 is used.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DIR_OPEN_ADAPTER_PARMS


LLC_DLC_REALLOCATE_PARMS

The LLC_DLC_REALLOCATE_PARMS structure is the DLC parameter table for the LLC_DLC_REALLOCATE_STATION command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    UCHAR uchOption;
    UCHAR uchStationCount;
    UCHAR uchStationsAvailOnAdapter;
    UCHAR uchStationsAvailOnSap;
    UCHAR uchTotalStationsOnAdapter;
    UCHAR uchTotalStationsOnSap;
} LLC_DLC_REALLOCATE_PARMS, *PLLC_DLC_REALLOCATE_PARMS;

Members

usStationId
Identifier of the affected SAP.
uchOption
The increase or decrease indicator. Specify one of the following values.
Value | Meaning
LLC_INCREASE_LINK_STATIONS | Increase the number of link stations.
LLC_DECREASE_LINK_STATIONS | Decrease the number of link stations.

uchStationCount
Number of link stations to be reallocated as indicated by the uchOption member. If this number is greater than the number of available stations, the command fails and LLC_STATUS_INADEQUATE_LINKS is the return code. If this value is zero, the command is executed and returns the values in the parameter table.
uchStationsAvailOnAdapter
Number of link stations available for this adapter.
uchStationsAvailOnSap
Number of link stations available for this SAP.
uchTotalStationsOnAdapter
Number of link stations configured for this adapter.
uchTotalStationsOnSap
Number of link stations reserved for this SAP.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_SET_THRESHOLD_PARMS

The LLC_DLC_SET_THRESHOLD_PARMS structure is the DLC parameter table for the LLC_DLC_SET_THRESHOLD command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    USHORT cBufferThreshold;
    PVOID AlertEvent;
} LLC_DLC_SET_THRESHOLD_PARMS, *PLLC_DLC_SET_THRESHOLD_PARMS;

Members

usStationId
SAP station identifier.
cBufferThreshold
SAP buffer pool threshold number. If the number of buffers in the SAP buffer pool is less than this threshold, the AlertEvent member is signaled.
AlertEvent
Event used to alert the application that the buffer threshold has been exceeded.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_DLC_STATISTICS_PARMS

The LLC_DLC_STATISTICS_PARMS structure is the DLC parameter table for the LLC_DLC_STATISTICS command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    USHORT cbLogBufSize;
    PLLC_DLC_LOG_BUFFER pLogBuf;
    USHORT usActLogLength;
    UCHAR uchOptions;
} LLC_DLC_STATISTICS_PARMS, *PLLC_DLC_STATISTICS_PARMS;

Members

usStationId
Identifier of a SAP or a link station.
cbLogBufSize
Size of the log buffer.
pLogBuf
Specifies the address of an LLC_DLC_LOG_BUFFER structure representing the log buffer.
usActLogLength
Length of returned log.
uchOptions
Command options. Specify one of the following options.
Option | Description
LLC_DLC_RESET_STATISTICS | The counters are reset to zero where appropriate.
LLC_DLC_READ_STATISTICS | The counters are read.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_DLC_LOG_BUFFER


LLC_EXTENDED_ADAPTER_PARMS

The LLC_EXTENDED_ADAPTER_PARMS structure represents the adapter parameter table for the LLC_DIR_OPEN_ADAPTER command. You pass a pointer to this structure in the LLC_DIR_OPEN_ADAPTER_PARMS structure.

typedef struct {
    PVOID hBufferPool;
    PVOID pSecurityDescriptor;
    LLC_ETHERNET_TYPE LlcEthernetType;
} LLC_EXTENDED_ADAPTER_PARMS, *PLLC_EXTENDED_ADAPTER_PARMS;

Members

hBufferPool
Handle to a buffer pool. The handle must have been created using the LLC_BUFFER_CREATE command.
pSecurityDescriptor
Windows NT: An optional security descriptor.

Windows 95 and Windows 98: This member is not used.

LlcEthernetType
Specifies an LLC_ETHERNET_TYPE value representing the Ethernet type. LLC_ETHERNET_TYPE is an enumerated type. The following values are defined.
Value | Meaning
LLC_ETHERNET_TYPE_DEFAULT | Use the parameter value set in the registry.
LLC_ETHERNET_TYPE_AUTO | Use automatic header type selection for links.
LLC_ETHERNET_TYPE_802_3 | Always use 802.3 LAN headers.
LLC_ETHERNET_TYPE_DIX | Always use LLC on DIX SNA type.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_DIR_OPEN_ADAPTER_PARMS


LLC_NEXT_BUFFER

The LLC_NEXT_BUFFER structure represents a buffer for received data. Specify this structure in the LLC_BUFFER structure.

typedef struct {
    PLLC_BUFFER pNextBuffer;
    USHORT cbFrame;
    USHORT cbBuffer;
    USHORT offUserData;
    USHORT cbUserData;
} LLC_NEXT_BUFFER;

Members

pNextBuffer
Specifies the address of an LLC_BUFFER structure representing the next buffer in the frame.
cbFrame
Length of the entire frame received.
cbBuffer
Length of the segment.
offUserData
Offset of data from the header.
cbUserData
Length of the data.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_BUFFER


LLC_NOT_CONTIGUOUS_BUFFER

The LLC_NOT_CONTIGUOUS_BUFFER structure represents a buffer for the received data. Specify this structure in the LLC_BUFFER structure.

typedef struct {
    PLLC_BUFFER pNextBuffer;
    USHORT cbFrame;
    USHORT cbBuffer;
    USHORT offUserData;
    USHORT cbUserData;
    USHORT usStationId;
    UCHAR uchOptions;
    UCHAR uchMsgType;
    USHORT cBuffersLeft;
    UCHAR uchRcvFS;
    UCHAR uchAdapterNumber;
    PLLC_BUFFER pNextFrame;
    UCHAR cbLanHeader;
    UCHAR cbDlcHeader;
    UCHAR auchLanHeader[32];
    UCHAR auchDlcHeader[4];
    USHORT usPadding;
} LLC_NOT_CONTIGUOUS_BUFFER;

Members

pNextBuffer
Specifies the address of an LLC_BUFFER structure representing the next buffer in the frame.
cbFrame
Length of the entire frame.
cbBuffer
Length of the buffer.
offUserData
User data in the structure.
cbUserData
Length of user data.
usStationId
Station identifier.
uchOptions
Option byte from RECEIVE parameter table.
uchMsgType
Specifies an LLC_FRAME_TYPES value representing the message type. LLC_FRAME_TYPES is an enumerated type. The following values are defined.
Value | Meaning
LLC_DIRECT_MAC | MAC frame (direct station on Token-Ring network only).
LLC_I_FRAME | Information frame (link stations only).
LLC_UI_FRAME | UI frame.
LLC_XID_COMMAND_POLL | XID command (poll bit).
LLC_XID_COMMAND_NOT_POLL | XID command (not poll bit).
LLC_XID_RESPONSE_FINAL | XID response (final bit).
LLC_XID_RESPONSE_NO_FINAL | XID response (not final bit).
LLC_TEST_RESPONSE_FINAL | TEST response (final bit).
LLC_TEST_RESPONSE_NOT_FINAL | TEST response (not final bit).
LLC_DIRECT_8022 | 802.2 frame (direct station only).
LLC_DIRECT_ETHERNET_TYPE | Ethernet frame (direct station only).

cBuffersLeft
Number of basic buffer units left.
uchRevFS
The received frame status (Token-Ring network only). This member is an 8-bit value. Setting the various bits enables different options, as described in the following table.
Bit | Description
7 | Address recognized indicator.
6 | Frame copied indicator.
5 | Reserved.
4 | Reserved.
3 | Address recognized indicator.
2 | Frame copied indicator.
1 | Reserved.
0 | Reserved.

uchAdapterNumber
Adapter number.
pNextFrame
Specifies the address of an LLC_BUFFER structure representing the next frame.
cbLanHeader
Length of the LAN header.
cbDlcHeader
Length of the DLC header.
auchLanHeader
LAN header of the received frame.
auchDlcHeader
DLC header of the received frame.
usPadding
Padding bytes. Data begins from offset 64.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_BUFFER, LLC_CCB


LLC_READ_PARMS

The LLC_READ_PARMS structure is the DLC parameter table for the LLC_READ command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    UCHAR uchOptionIndicator;
    UCHAR uchEventSet;
    UCHAR uchEvent;
    UCHAR uchCriticalSubset;
    ULONG ulNotificationFlag;
    union {
        struct {
            USHORT usCcbCount;
            PLLC_CCB pCcbCompletionList;
            USHORT usBufferCount;
            PLLC_BUFFER pFirstBuffer;
            USHORT usReceivedFrameCount;
            PLLC_BUFFER pReceivedFrame;
            USHORT usEventErrorCode;
            USHORT usEventErrorData[3];
        } Event;
        struct {
            USHORT usStationId;
            USHORT usDlcStatusCode;
            UCHAR uchFrmrData[5];
            UCHAR uchAccessPritority;
            UCHAR uchRemoteNodeAddress[6];
            UCHAR uchRemoteSap;
            UCHAR uchReserved;
            USHORT usUserStatusValue;
        } Status;
    } Type;

} LLC_READ_PARMS, *PLLC_READ_PARMS;

Members

usStationId
SAP station identifier.
uchOptionIndicator
Read option indicator. Specify one of the following values.
Value | Description
LLC_OPTION_READ_STATION | Match the read command using the station identifier.
LLC_OPTION_READ_SAP | Match the read command using the SAP number of the station identifier.
LLC_OPTION_READ_ALL | Match the read command using all events.

uchEventSet
Set of events for notification. Specify one of the following values.
Value | Description
LLC_READ_ALL_EVENTS | All events.
LLC_EVENT_SYSTEM_ACTION | System action events.
LLC_EVENT_NETWORK_STATUS | Network status events (non-critical).
LLC_EVENT_CRITICAL_EXCEPTION | Critical exception.
LLC_EVENT_STATUS_CHANGE | DLC status change.
LLC_EVENT_RECEIVE_DATA | Receive data.
LLC_EVENT_TRANSMIT_COMPLETION | Transmit completion.
LLC_EVENT_COMMAND_COMPLETION | Command completion.

uchEvent
Posting event. Receives one of the LLC_EVENT constants described in uchEventSet.
uchCriticalSubset
Critical event subset identifier. This member receives one of the following values.
Value | Description
1 | Network status
2 | Adapter check
3 | System error
4 | System action

ulNotificationFlag
Event user notification flag. This member receives the DLC status flag, as defined with the LLC_DLC_OPEN_SAP command, for the link station that experienced the change.
usCcbCount
Count of command control blocks chained to pCcbCompletionList.
pCcbCompletionList
Specifies the address of the command control blocks.
usBufferCount
Count of buffers chained to pFirstBuffer.
pFirstBuffer
Address of the first buffer of received data.
usReceivedFrameCount
Count of received frames chained to pReceivedFrame.
pReceivedFrame
Address of the received frame.
usEventErrorCode
Exception code.
usEventErrorData
Exception parameters.
usStationId
SAP or link station identifier.
usDlcStatusCode
DLC status code. This member receives one or more of the following values.
Code | Name
0x8000 | LLC_INDICATE_LINK_LOST
0x4000 | LLC_INDICATE_DM_DISC_RECEIVED
0x2000 | LLC_INDICATE_FRMR_RECEIVED
0x1000 | LLC_INDICATE_FRMR_SENT
0x0800 | LLC_INDICATE_RESET
0x0400 | LLC_INDICATE_CONNECT_REQUEST
0x0200 | LLC_INDICATE_REMOTE_BUSY
0x0100 | LLC_INDICATE_REMOTE_READY
0x0080 | LLC_INDICATE_TI_TIMER_EXPIRED
0x0040 | LLC_INDICATE_DLC_COUTNER_OVERFLOW
0x0020 | LLC_INDICATE_ACCESS_PRTY_LOWERED
0x0001 | LLC_INDICATE_LOCAL_STATION_BUSY

uchFrmrData
Frame data.
uchAccessPriority
The new Token-Ring access priority. This value is not recognized on other networks.
uchRemoteNodeAddress
Remote node address.
uchRemoteSap
Remote SAP address.
uchReserved
Reserved.
usUserStatusValue
User status value.

Remarks

The following table shows which members are used for each event.

Event | Members used
LLC_EVENT_SYSTEM_ACTION | ulNotificationFlag usCcbCount pCcbCompletionList usBufferCount pFirstBuffer usReceivedFrameCount pReceivedFrame usEventErrorCode usEventErrorData
LLC_EVENT_NETWORK_STATUS | ulNotificationFlag usEventErrorCode
LLC_EVENT_CRITICAL_EXCEPTION | uchCriticalSubset ulNotificationFlag usCcbCount pCcbCompletionList usBufferCount pFirstBuffer usReceivedFrameCount pReceivedFrame usEventErrorCode usEventErrorData
LLC_EVENT_STATUS_CHANGE | ulNotificationFlag usStationId usDlcStatusCode uchFrmrData uchAccessPriority uchRemoteNodeAddress uchRemoteSap usUserStatusValue
LLC_EVENT_RECEIVE_DATA | usReceivedFrameCount pReceivedFrame
LLC_EVENT_TRANSMIT_COMPLETION | usCcbCount pCcbCompletionList
LLC_EVENT_COMMAND_COMPLETION | usCcbCount pCcbCompletionList usBufferCount pFirstBuffer usReceivedFrameCount pReceivedFrame

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_RECEIVE_PARMS

The LLC_RECEIVE_PARMS structure is the DLC parameter table for the LLC_RECEIVE command. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    USHORT usUserLength;
    ULONG ulReceiveFlag;
    PLLC_BUFFER pFirstBuffer;
    UCHAR uchOptions;
    UCHAR auchReserved1[3];
    UCHAR uchRcvReadOption;
} LLC_RECEIVE_PARMS, *PLLC_RECEIVE_PARMS;

Members

usStationId
SAP or link station identifier.
usUserLength
Length of user data in buffer.
ulReceiveFlag
The received data handler.
pFirstBuffer
Specifies the address of an LLC_BUFFER structure, representing the first buffer in the pool.
uchOptions
Defines how the frame is received. Specify one of the following values.
Option | Description
LLC_CONTIGUOUS_MAC | Contiguous MAC. Used only with MAC frames.
LLC_CONTIGUOUS_DATA | Contiguous data. Only used with non-MAC frames. The system places the entire frame in the first buffer.
LLC_NOT_CONTIGUOUS_DATA | The first data received is placed in the second buffer. The first buffer contains only the header data.

auchReserved1
Reserved.
uchRcvReadOption
Defines how RCV frames are chained. Specify one of the following values.
Option | Description
LLC_RCV_READ_INDIVIDUAL_FRAMES | The frames are not chained. Use an LLC_READ command to retrieve each frame.
LLC_RCV_CHAIN_FRAMES_ON_LINK | The frames received for a link station are chained. You can use a single LLC_READ command to retrieve all chained frames.
LLC_RCV_CHAIN_FRAMES_ON_SAP | The frames received for a SAP are chained. You can use a single LLC_READ command to retrieve all chained frames.

Remarks

If LLC_RECEIVE commands have been issued for link stations, the options specified for the link station's LLC_RECEIVE command determine how received data is chained. If a link station has a pending LLC_RECEIVE command specifying that its received frames should be chained on a link station basis, its frames will not be chained together with the SAP's frames. All link stations that do not have an LLC_RECEIVE command pending will have their received frames chained as specified by the SAP's LLC_RECEIVE command. If neither the SAP nor the link station have an LLC_RECEIVE command pending, the direct station is used.

The uchRcvReadOption member of a SAP's LLC_RECEIVE command is used to determine how data that the link station receives for the SAP is chained when its link stations do not have LLC_RECEIVE commands outstanding.

LLC_READ commands must match the LLC_RECEIVE commands uchRcvReadOption settings.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS, LLC_BUFFER


LLC_TRANSMIT_PARMS

The LLC_TRANSMIT_PARMS structure is the DLC parameter table for the LLC_TRANSMIT commands. You pass a pointer to this structure using the pParameterTable member of the CCB_PARMS union.

typedef struct {
    USHORT usStationId;
    UCHAR uchTransmitFs;
    UCHAR uchRemoteSap;
    PLLC_XMIT_BUFFER pXmitQueue1;
    PLLC_XMIT_BUFFER pXmitQueue2;
    USHORT cbBuffer1;
    USHORT cbBuffer2;
    PVOID pBuffer1;
    PVOID pBuffer2;
    UCHAR uchXmitReadOption;
} LLC_TRANSMIT_PARMS, *PLLC_TRANSMIT_PARMS;

Members

usStationId
Specifies the station sending the data.
uchTransmitFs
The FS field returned by the adapter or protocol driver. On Ethernet, this field is zero. If the command succeeds, the return code is zero; otherwise, the return code is nonzero.
uchRemoteSap
The SAP value of the remote SAP that the local SAP is communicating with. This value is ignored if the sending station is a link station or a direct station.
pXmitQueue1
Specifies the address of the first (or only) buffer in a queue of buffers to be transmitted or NULL. The data in all buffers is transmitted as one frame.
pXmitQueue2
Specifies the address of the first (or only) buffer in a second queue of buffers to be transmitted or NULL. The data in all buffers is transmitted as one frame following the frame that contains the pXmitQueue1 buffers.
cbBuffer1
The length of the buffer for transmitting data pointed to by pBuffer1. If this member is zero, the cbBuffer2, pBuffer1, and pBuffer2 members are ignored.
cbBuffer2
The length of the buffer for transmitting data pointed to by pBuffer1. If this member is zero, this buffer is not used.
pBuffer1
Specifies the address of the buffer containing the data to be transmitted. The data is transmitted as one frame following the data in pXmitQueue1 and pXmitQueue2.
pBuffer2
Specifies the address of the buffer containing the data to be transmitted. The data is transmitted as one frame following the data in pXmitQueue1, pXmitQueue2, and pBuffer1.
uchXmitReadOption
Defines whether LLC_TRANSMIT commands are chained together when they complete. Specify one of the following values.
Option | Description
LLC_CHAIN_XMIT_COMMANDS_ON_LINK | Chain the command on a link station basis.
LLC_COMPLETE_SINGLE_XMIT_FRAME | Do not chain the command.
LLC_CHAIN_XMIT_COMMANDS_ON_SAP | Chain the command on a SAP station basis.

Remarks

This structure is used by all the LLC_TRANSMIT commands. The following table describes the information you must supply for each command.

Command | Command Specifics
LLC_TRANSMIT_DIR_FRAME | The entire frame must be prepared by the application. The LAN header must reserve space for the adapter to insert the source address.
LLC_TRANSMIT_I_FRAME | The only data supplied by the application is the actual data portion.
LLC_TRANSMIT_UI_FRAME | The adapter provides the DLC header information. The application program must provide the LAN header and data portions of the message. The first buffer contains only the LAN header.
LLC_TRANSMIT_XID_CMD | The user provides the LAN header and data portion. The user must leave room for the DLC header provided by the protocol driver. The first buffer must contain only the LAN header.
LLC_TRANSMIT_XID_RESP_FINAL | The user provides the LAN header and data portion. The user must leave room for the DLC header provided by the protocol driver. The first buffer must contain only the LAN header.
LLC_TRANSMIT_XID_RESP_NOT_FINAL | The user provides the LAN header and data portion. The user must leave room for the DLC header provided by the protocol driver. The first buffer must contain only the LAN header.
LLC_TRANSMIT_TEST_CMD | The adapter provides the DLC header. The application program provides the LAN header and the optional test information. The first buffer must contain only the LAN header.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, CCB_PARMS


LLC_XMIT_BUFFER

The LLC_XMIT_BUFFER structure represents a pool buffer. You pass a pointer to this structure in the LLC_BUFFER_FREE_PARMS, LLC_BUFFER_GET_PARMS, or LLC_TRANSMIT_PARMS structure.

typedef struct _LLC_XMIT_BUFFER LLC_XMIT_BUFFER, *PLLC_XMIT_BUFFER;

struct _LLC_XMIT_BUFFER {
    PLLC_XMIT_BUFFER pNext;
    USHORT usReserved1;
    USHORT cbBuffer;
    USHORT usReserved2;
    USHORT cbUserData;
    UCHAR auchData[];
};

Members

pNext
Next buffer or NULL.
usReserved1
Reserved.
cbBuffer
Length of the transmitted data.
usReserved2
Reserved.
cbUserData
Length of the optional header.
auchData
Optional header and transmitted data.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in dlcapi.h.

See Also

The DLC Interface Overview, DLC Structures, AcsLan, LLC_BUFFER_FREE_PARMS, LLC_BUFFER_GET_PARMS, LLC_TRANSMIT_PARMS


The NetBIOS Interface

A Win32-based application can use the Network Basic Input/Output System (NetBIOS) interface to communicate with applications on other computers in a network. The NetBIOS interface provides commands and support for the following services:

  • Network name registration and verification
  • Session establishment and termination
  • Reliable connection-oriented data transfer
  • Unreliable connectionless data transfer (datagram)
  • Protocol and adapter monitoring and management

The NetBIOS interface exposes an explicit set of commands that are submitted through a structure known as the network control block (NCB). An application can issue NetBIOS commands over any protocol that supports the NetBIOS interface.


About the NetBIOS Interface

The NetBIOS interface is provided primarily for existing applications that use IBM NetBIOS 3.0 and need to be ported to the Win32 API. New applications and applications not requiring compatibility with NetBIOS should use other interfaces, such as mailslots, named pipes, RPC, sockets, or distributed COM to accomplish tasks similar to those supported by NetBIOS. These interfaces are more flexible and portable than NetBIOS. In addition, you can use sockets over NetBIOS to communicate with NetBIOS applications.

The Netbios function takes one parameter, a pointer to a structure describing the NCB. The NCB structure contains information about the command to perform, an optional post routine, an optional event handle, and a pointer to a buffer that is used for messages or other data.

This overview discusses the following topics:

  • NetBIOS Operation
  • NetBIOS LANA Numbers
  • NetBIOS Name Table
  • NetBIOS Session
  • NetBIOS Enhancements
  • NetBIOS Commands

The NetBIOS Requests for Comments (RFC) are 1001, 1002, and 1088. For more information on NetBIOS 3.0, contact IBM and order the IBM Local Area Network Technical Reference: IEEE 802.2 and NETBIOS Application Programming Interfaces.


NetBIOS Operation

Protocol drivers expose the NetBIOS interface and map NetBIOS commands to their own native commands. The NetBIOS Frames protocol (NBFP) can be implemented by the underlying protocol software to perform the network I/O required by the NetBIOS interface.

The Windows NT NetBIOS emulator accepts NetBIOS commands, translates them to Transport Driver Interface (TDI) calls, and forwards them to the transport driver using the TDI interface. NetBIOS emulation requires some functionality that is not required for all TDI drivers. A TDI driver that provides this functionality is called a NetBIOS-compatible TDI driver.

The following illustration shows how NetBIOS works on Windows NT.

In Windows NT, the NetBIOS over TCP/IP (NetBT or NBT) protocol provides NetBIOS support for the TCP/IP protocol. It is defined by RFCs 1001 and 1002. The NetBIOS over NetBEUI protocol provides NetBIOS support for the NetBEUI protocol. This protocol is also called NetBIOS Frames (NBF). The NetBIOS over IPX (NBIPX) protocol provides IPX support. This protocol is also called NetBIOS on NetWare (NWNBLINK). It is based on Novell's NetBIOS.

For more information about the protocol and driver layers and the TDI interface, see the Win32 Device Development Kit (DDK) documentation.


NetBIOS LANA Numbers

The NetBIOS LANA number identifies the transport driver, network interface card (NIC) driver, and adapter that will be used to send and receive NetBIOS packets. This is known as the network route. The following example shows the network route that will be used when you specify a LANA value of 1:

001 NetBT -> IEEPRO -> IEEPRO1

Specify the LANA number in the ncb_lana_num member of the NCB structure when you issue a NetBIOS command.

The IBM NetBIOS 3.0 specification supports only two LANA numbers, because NetBEUI was originally the only protocol that supported NetBIOS, and a computer could contain only two network adapters at that time. Specifying LANA 0 directed a command to the first adapter, and specifying LANA 1 directed a command to the second adapter. Because many computers had only one network adapter, many MS-DOS – based applications sent all their requests to LANA 0. If a second network adapter was installed, some applications allowed the user to specify the use of LANA 1 instead. As a result, LANA 0 became the default setting, though it was never intended as such.

Windows NT enables NetBIOS to use transport protocols other than NetBEUI. Therefore, Microsoft has extended the meaning of a LANA number to indicate a specific transport protocol on a specific adapter. For example, if you have two network adapters, and have three transport protocols installed, you have six LANA numbers. The LANA numbers are not necessarily sequential.

In addition to extending the meaning of a LANA number, Microsoft also added the NCBENUM command to enumerate the available LANA numbers. As an example, the LANA_ENUM structure filled by NCBENUM might hold an array with values 0, 3, 5, and 6. Zero might map to IPX/SPX on the first adapter, three might map to NETBEUI on a second adapter, and so on.

Windows NT: You can associate specific LANA numbers with specific network routes using the following steps.

To associate a LANA number with a network route on Windows NT
  1. Start the Network Control Panel application.
  2. Click the Services tab.
  3. Double-click NetBIOS Interface.
  4. Click the LANA number you want to change.
  5. Enter the new LANA number to be associated with the network route.

Windows 95 and Windows 98: You cannot configure LANA numbers because of the way plug and play was designed. LANA numbers can change as users install plug and play devices. You may set only LANA 0, which is the default protocol. The next protocol is LANA 7, then LANA 6, and so on. If no protocol is set as the default, there may not be a LANA 0.

You can set the default protocol in the control panel using the following steps:

To set LANA 0 on Windows 95 or Windows 98
  1. Start the Network Control Panel application.
  2. Choose the protocol you want as the default.
  3. Click Properties.
  4. Click the Advanced tab.
  5. Click Set this protocol to be the default protocol.

The best way to write a NetBIOS application is to support all LANA numbers, and establish connections over any LANA number. This allows your application to transparently support any transport protocol that supports NetBIOS, as well as dynamic LANA numbers associated with dial-up adapters or plug-and-play hardware. A good approach is outlined in the following steps.

To support connections over any LANA
  1. Enumerate the LANA numbers by issuing an NCBENUM command.
  2. Reset each LANA by issuing one NCBRESET command per LANA number.
  3. Add your local NetBIOS name to each LANA. The name may be the same on each LANA.
  4. Connect using any LANA number:
    • For servers, issue an NCBLISTEN command on each LANA. If necessary, cancel any outstanding listen operation after the first listen operation has been completed.
    • For clients, issue an NCBFINDNAME (Windows NT only) or an NCBCALL (Windows NT, Windows 95, or Windows 98) command on each LANA. The first successful NCBFINDNAME or NCBCALL operation will indicate which LANA to use. When using NCBCALL instead of NCBFINDNAME, you must cancel any pending NCBCALL commands and hang up any extra completed calls.

Though this is the best technique for writing a NetBIOS application, it generates several datagrams, making the NetBIOS interface less desirable than other networking interfaces.


NetBIOS Name Table

NetBIOS names are used as the basis for communication between applications. NetBIOS maintains a name table for each LANA for each process that contains the names by which the process is known on the network. These names are used when forming connections between processes.

Names are provided to NetBIOS by the application through the ncb_name member of the NCB structure. A name can be a unique name or a group name. NetBIOS checks the network to verify that a unique name is not already in use by another adapter. A group name can be used by several adapters.

NetBIOS names can be up to 16 characters long. This is large enough to accommodate a text version of the media access control (MAC) address, plus a few other characters. Using the MAC address in this way results in a name that is guaranteed unique on any network. The name NAME_NUMBER_1 is always present and has the value 1.

For more information, see Name Support.


NetBIOS Session

A NetBIOS session is a logical connection between any two processes on the network. The NetBIOS local session number identifies the virtual circuit established between two processes. Local session numbers are provided to applications by NetBIOS through the ncb_lsn member of the NCB structure.

To establish a session, have one process issue an NCBLISTEN command, and have the other process issue an NCBCALL command. After a session is established, the computers can exchange data using NetBIOS commands.

Each process can establish 254 sessions per LANA number. Because names are maintained on a per-process basis, the NetBIOS emulator can identify two separate sessions even if they have the same local session number in their respective processes. The emulator maps each local session number to a unique TDI connection endpoint handle.

For more information, see Session Support.


NetBIOS Enhancements

The Win32 implementation of NetBIOS is based on the NetBIOS 3.0 specification. However, the Win32 implementation includes the following enhancements that are not part of the NetBIOS 3.0 specification:

  • NetBIOS emulator manages resources separately per process. For example, the network name numbers are assigned on a per-process basis. Therefore, if a process issues the NCBRESET command, the names, sessions, and outstanding NCBs allocated for that process are cleared, but those of other processes are not affected. Also, requests for the status of the local adapter retrieve only the names that were added by the process making the request.
  • The NetBIOS emulator supports 254 sessions per process, per LANA number.
  • You can supply an event in the ncb_event member of the NCB structure. This is not a standard NetBIOS 3.0 NCB member. The event is set to the signaled state when NetBIOS completes an asynchronous command. This method of issuing asynchronous commands is faster than using post routines and it uses fewer system resources. The system creates an event and a worker thread for each command that uses a post routine.
  • A process can enable extensions to the transport interface by using the NCBACTION command in the ncb_command member of the NCB structure. This is not a standard NetBIOS 3.0 command.
  • A process can enumerate all available LAN adapters by using the NCBENUM command in the ncb_command member of the NCB structure. This is not a standard NetBIOS 3.0 command.
  • A process is required to issue the NCBRESET command on each LANA number before it can issue any other NetBIOS command on the LANA number, with the exception of NCBENUM.
  • The NetBIOS 3.0 specification allows LANA numbers 0 and 1. Win32 allows additional LANA numbers.
  • The value 1 for the ncb_num member of the NCB structure is not exclusive when the NCBRESET command is issued. All MS-DOS and 16-bit Windows-based applications also share access to NAME_NUMBER_1.


NetBIOS Commands

A NetBIOS application issues commands to an underlying transport driver using the Netbios function. You provide information in the NCB structure. The appropriate transport driver receives the information, performs the command, and reports status by filling in selected NCB members.

When a command is issued synchronously, Netbios does not return until the protocol driver completes the command. Both the ncb_retcode and ncb_cmd_cplt members contain the return value.

When a command is issued asynchronously, Netbios does not return until the protocol driver checks the command syntax, cehcks whether the session is valid, and checks whether there are sufficient available resources. Both the ncb_retcode and ncb_cmd_cplt members contain the return value. The return value is an error code if the command was not successfully queued. A return value of NRC_PENDING indicates that the protocol driver has successfully queued the command. When the protocol driver completes the command, it places the final return value in both the ncb_retcode and ncb_cmd_cplt members. If the ncb_post member specifies a post routine, the protocol driver calls the post routine.

Post routines are called in the context of the calling process. The post routine in a Win32-based application typically posts a message to an appropriate window and then exits. The thread that receives the message uses it as an indication that the asynchronous command has been completed. The system creates an event and a worker thread for each command that uses a post routine. As a result, it is faster to use the ncb_event member instead of a post routine for asynchronous commands.

The NetBIOS commands can be divided into the following categories:

  • Name Support
  • Session Support
  • Data-Transfer Support
  • Datagram Support
  • General Support
  • Windows NT Extensions


Name Support

The following are the name support commands:

  • NCBADDGRNAME (add group name)
  • NCBADDNAME (add name)
  • NCBDELNAME (delete name)
  • NCBFINDNAME (find name)

The NCBADDGRNAME and NCBADDNAME commands register names. The transport driver verifies the name, registers it in the name table, and returns a corresponding name number in the ncb_num member of the NCB structure. The registration process is shown in the following illustration. The names "station1" and "station2" will be used in subsequent examples.

The NCBFINDNAME command obtains the MAC header information for the computer that has registered the specified name. The protocol driver queries the network for the specified name. If any computers have registered the name, they respond with an indication of whether the name is a unique name or a group name. Multiple computers may respond. The ncb_buffer member receives a FIND_NAME_HEADER structure, followed by one or more FIND_NAME_BUFFER structures. The length of the buffer is returned in the ncb_length member. This process is shown in the following illustration.

The NCBDELNAME command deletes a name from its name table. Names are stored with a reference to the process that registered the name and a corresponding LANA number. A process cannot delete a name that was added by another process, even if it has the name number. The deletion process is shown in the following illustration.


Session Support

The following are the session support commands:

  • NCBCALL (call)
  • NCBHANGUP (hang up)
  • NCBLISTEN (listen)
  • NCBSSTAT (session status)

The NCBCALL and NCBLISTEN commands establish a session between processes. One process issues the NCBLISTEN command to prepare to open a session. The other process issues the NCBCALL command to open the session. The remote computer must have an NCBLISTEN command pending. When the session is established, the NCBLISTEN command is completed and the calling process receives a local session number and the name of the remote session partner. In addition, the NCBCALL command is completed and the calling process receives a local session number in the ncb_lsn member of the NCB structure. The process of establishing a session is shown in the following illustration:

The NCBSSTAT command obtains the status of any sessions that were opened using the specified name. The ncb_buffer member receives a SESSION_HEADER structure, followed by one or more SESSION_BUFFER structures. The process of obtaining the session status is shown in the following illustration.

The NCBHANGUP command closes the session identified by the specified local session number, as shown in the following illustration.

This example assumes that there are NCBRECVANY commands pending on both computers.


Data-Transfer Support

The following are the data-transfer support commands:

  • NCBCHAINSEND (chain send)
  • NCBCHAINSENDNA (chain send noack)
  • NCBRECV (receive)
  • NCBRECVANY (receive any)
  • NCBSEND (send)
  • NCBSENDNA (send noack)

These commands provide reliable connection-oriented data transfer between session partners. Each data block is sent as a single message and received as a single message. The buffer supplied on a receive request must be large enough to hold an entire incoming message. If the receiving transport driver does not have enough space to store the message in the client-supplied buffer, it returns an error indicating that the buffer does not contain the entire message. The client must issue a subsequent receive command to obtain the remaining portion of the message.

The NCBSEND and NCBRECV commands transfer a single data buffer to the specified session partner, as shown in the following illustration.

The NCBRECVANY command receives data from any session that was opened with the specified name, as shown in the following illustration.

The NCBCHAINSEND command sends two data buffers to the specified session partner as one message. The NCBSENDNA and NCBCHAINSENDNA commands are similar to the NCBSEND and NCBCHAINSEND commands, respectively. However, no acknowledgment is required.


Datagram Support

The following are the datagram support commands:

  • NCBDGRECV (receive datagram)
  • NCBDGRECVBC (receive broadcast datagram)
  • NCBDGSEND (send datagram)
  • NCBDGSENDBC (send broadcast datagram)

Datagram support provides unreliable connectionless data transfer. The message is a single data frame whose size is limited to a MAC frame minus any headers. The protocol driver ensures that the message is transmitted to the network medium. The receiver does not generate a response to the sender to indicate that the datagram was received. Therefore, unreliable connectionless data transfer requires fewer system resources than reliable connection-oriented data transfer.

The NCBDGRECV and NCBDGSEND commands transfer a datagram to a specified NetBIOS name. If the specified name is a unique name, the datagram is received by the single process that registered the name. If the specified name is a group name, the datagram is received by all processes that registered the name. This process is shown in the following illustration.

The NCBDGSENDBC command broadcasts a datagram to all computers on the network. The datagram is received by all processes that have issued the NCBDGRECVBC command, as shown in the following illustration.


General Support

The following are the general support commands:

  • NCBASTAT (adapter status)
  • NCBCANCEL (cancel)
  • NCBRESET (reset)

The NCBRESET command clears the name and session tables. It also ends all pending commands and sessions for the network route specified by the ncb_lana_num member of the NCB structure. A process is required to issue the NCBRESET command on each LANA number before it can issue any other NetBIOS command on the LANA number, with the exception of NCBENUM. This process is shown in the following illustration.

The NCBASTAT command returns the current status and operation information about the network route specified in the ncb_lana_num member of the NCB structure. The ncb_buffer member receives an ADAPTER_STATUS structure, followed by an array of NAME_BUFFER structures.

The NCBASTAT command can be issued for the local computer or a remote computer. If the ncb_callname member contains an asterisk (*), information is returned for the local computer. If ncb_callname contains a NetBIOS name, the transport provider requests information from the remote computer where the name is registered, as shown in the following illustration.

The NCBCANCEL command cancels the command listed in the ncb_command member of the NCB structure passed to the Netbios function. NCBCANCEL closes the associated session when canceling the following commands:

  • NCBCALL
  • NCBCHAINSEND
  • NCBHANGUP
  • NCBLISTEN
  • NCBSEND

The emulator simply returns NRC_CMDCAN if the following commands are successfully canceled or it returns NRC_CANOCCR if they finish before they could be canceled:

  • NCBDGRECV
  • NCBDGRECVBC
  • NCBLANSTALERT
  • NCBRECV
  • NCBRECVANY

The following commands cannot be canceled:

  • NCBADDGRNAME
  • NCBADDNAME
  • NCBCANCEL
  • NCBDELNAME
  • NCBDGSEND
  • NCBDGSENDBC
  • NCBRESET
  • NCBSSTAT

An asynchronous NCBACTION command cannot be canceled using NCBCANCEL. To cancel a synchronous NCBACTION command, the transport provider must support an action code that cancels other action codes. Alternatively, you can cancel the command by hanging up the session, deleting the name, or resetting the LANA number.


Windows NT Extensions

The following commands are Windows NT extensions to the NetBIOS interface:

  • NCBACTION (action)
  • NCBENUM (enumerate)
  • NCBLANSTALERT (LAN status alert)

The NCBACTION command enables extensions to the NetBIOS interface. The ncb_buffer member of the NCB structure points to an ACTION_HEADER structure, which specifies the transport provider and the provider-defined action code. The process of issuing the NCBACTION command is shown in the following illustration.

The NCBENUM command enables enumeration of all LANA numbers. The ncb_buffer member of the NCB structure points to a LANA_ENUM structure, which specifies how many valid LANA numbers were returned, and an array of LANA numbers. The process of issuing the NCBENUM command is shown in the following illustration.

The NCBLANSTALERT command notifies the user of catastrophic network failures, which can occur, for example, when there are duplicate names on the network. NCBLANSTALERT is typically issued as an asynchronous command. The command returns if an error occurs. At that time, the application should cease to use the network route. When the command returns, ncb_retcode does not indicate the error status associated with the network error condition. It indicates the success or failure of the NCBLANSTALERT command. The process of issuing the NCBLANSTALERT command is shown in the following illustration.


Using the NetBIOS Interface

  • Listing All NetBIOS Names on a LANA
  • Getting the MAC Address for an Ethernet Adapter


Listing All NetBIOS Names on a LANA

You can use the Netbios function to list all the NetBIOS names on a LANA. The following example uses a unique name as the name in the ncb_callname member of the NCB structure. This causes the adapter status to be treated as a remote call, which enables you to retrieve names added by other processes.

// Set LANANUM and LOCALNAME as appropriate for your system
#define LANANUM     0
#define LOCALNAME   "MAKEUNIQUE"
#define NBCheck(x)  if (NRC_GOODRET != x.ncb_retcode) { \
                        printf("Line %d: Got 0x%x from NetBios()\n", \
                               __LINE__, x.ncb_retcode); \
                    }

void MakeNetbiosName (char *, LPCSTR);
BOOL NBAddName (int, LPCSTR);
BOOL NBReset (int, int, int);
BOOL NBListNames (int, LPCSTR);
BOOL NBAdapterStatus (int, PVOID, int, LPCSTR);

void main ()
{
    if (!NBReset (LANANUM, 20, 30)) return;

    if (!NBAddName (LANANUM, LOCALNAME)) return;

    if (!NBListNames (LANANUM, LOCALNAME)) return;

    printf ("Succeeded.\n");
}

BOOL NBReset (int nLana, int nSessions, int nNames)
{
    NCB ncb;

    memset (&ncb, 0, sizeof (ncb));
    ncb.ncb_command = NCBRESET;
    ncb.ncb_lsn = 0;                // Allocate new lana_num resources
    ncb.ncb_lana_num = nLana;
    ncb.ncb_callname[0] = nSessions;  // maximum sessions
    ncb.ncb_callname[2] = nNames;   // maximum names

    Netbios (&ncb);
    NBCheck (ncb);

    return (NRC_GOODRET == ncb.ncb_retcode);
}

BOOL NBAddName (int nLana, LPCSTR szName)
{
    NCB ncb;

    memset (&ncb, 0, sizeof (ncb));
    ncb.ncb_command = NCBADDNAME;
    ncb.ncb_lana_num = nLana;

    MakeNetbiosName (ncb.ncb_name, szName);

    Netbios (&ncb);
    NBCheck (ncb);

    return (NRC_GOODRET == ncb.ncb_retcode);
}

// Build a name of length NCBNAMSZ, padding with spaces.
void MakeNetbiosName (char *achDest, LPCSTR szSrc)
{
    int cchSrc;

    cchSrc = lstrlen (szSrc);
    if (cchSrc > NCBNAMSZ)
        cchSrc = NCBNAMSZ;

    memset (achDest, ' ', NCBNAMSZ);
    memcpy (achDest, szSrc, cchSrc);
}

BOOL NBListNames (int nLana, LPCSTR szName)
{
    int cbBuffer;
    ADAPTER_STATUS *pStatus;
    NAME_BUFFER *pNames;
    int i;
    HANDLE hHeap;

    hHeap = GetProcessHeap();

    // Allocate the largest buffer that might be needed.
    cbBuffer = sizeof (ADAPTER_STATUS) + 255 * sizeof (NAME_BUFFER);
    pStatus = (ADAPTER_STATUS *) HeapAlloc (hHeap, 0, cbBuffer);
    if (NULL == pStatus)
        return FALSE;

    if (!NBAdapterStatus (nLana, (PVOID) pStatus, cbBuffer, szName))
    {
        HeapFree (hHeap, 0, pStatus);
        return FALSE;
    }

    // The list of names follows the adapter status structure.
    pNames = (NAME_BUFFER *) (pStatus + 1);

    for (i = 0; i < pStatus->name_count; i++)
        printf ("\t%.*s\n", NCBNAMSZ, pNames[i].name);

    HeapFree (hHeap, 0, pStatus);

    return TRUE;
}
BOOL NBAdapterStatus (int nLana, PVOID pBuffer, int cbBuffer, LPCSTR szName)
{
    NCB ncb;

    memset (&ncb, 0, sizeof (ncb));
    ncb.ncb_command = NCBASTAT;
    ncb.ncb_lana_num = nLana;

    ncb.ncb_buffer = (PUCHAR) pBuffer;
    ncb.ncb_length = cbBuffer;

    MakeNetbiosName (ncb.ncb_callname, szName);

    Netbios (&ncb);
    NBCheck (ncb);

    return (NRC_GOODRET == ncb.ncb_retcode);
}


Getting the MAC Address for an Ethernet Adapter

You can use the Netbios function to get the Media Access Control (MAC) address for an ethernet adapter if your card is bound to NetBIOS. The following example uses the NCBASTAT command, providing an asterisk (*) as the name in the ncb_callname member of the NCB structure.

Note The following code does not work reliably on Windows 95 or Windows 98.

#include <windows.h>
#include <wincon.h>
#include <stdlib.h>
#include <stdio.h>
#include <time.h>

typedef struct _ASTAT_
{
    ADAPTER_STATUS adapt;
    NAME_BUFFER    NameBuff [30];
}ASTAT, * PASTAT;

ASTAT Adapter;

void main (void)
{
    NCB ncb;
    UCHAR uRetCode;
    char NetName[50];

    memset( &ncb, 0, sizeof(ncb) );
    ncb.ncb_command = NCBRESET;
    ncb.ncb_lana_num = 0;

    uRetCode = Netbios( &ncb );
    printf( "The NCBRESET return code is: 0x%x \n", uRetCode );

    memset( &ncb, 0, sizeof(ncb) );
    ncb.ncb_command = NCBASTAT;
    ncb.ncb_lana_num = 0;

    strcpy( ncb.ncb_callname,  "*               " );
    ncb.ncb_buffer = (char *) &Adapter;
    ncb.ncb_length = sizeof(Adapter);

    uRetCode = Netbios( &ncb );
    printf( "The NCBASTAT return code is: 0x%x \n", uRetCode );
    if ( uRetCode == 0 )
    {
        printf( "The Ethernet Number is: %02x%02x%02x%02x%02x%02x\n",
                Adapter.adapt.adapter_address[0],
                Adapter.adapt.adapter_address[1],
                Adapter.adapt.adapter_address[2],
                Adapter.adapt.adapter_address[3],
                Adapter.adapt.adapter_address[4],
                Adapter.adapt.adapter_address[5] );
    }
}


NetBIOS Reference

The following functions and structures are used in NetBIOS.


NetBIOS Functions

The following function is used in NetBIOS.

Netbios


Netbios

The Netbios function interprets and executes the specified network control block (NCB).

The Netbios function is provided primarily for applications that were written for the NetBIOS interface and need to be ported to Win32. Applications not requiring compatibility with NetBIOS should use other interfaces, such as mailslots, named pipes, RPC, or distributed COM to accomplish tasks similar to those supported by NetBIOS. These other interfaces are more flexible and portable.

UCHAR Netbios(
  PNCB pncb   // pointer to the network control block
);

Parameters

pncb
Pointer to an NCB structure describing the network control block.

Return Values

For synchronous requests, the return value is the return code of the NCB structure. That value is also returned in the ncb_retcode member of the NCB structure.

For asynchronous requests, there are the following possibilities:

  • If the asynchronous command has already completed when Netbios returns to its caller, the return value is the return code of the NCB structure, just as if it were a synchronous NCB structure.
  • If the asynchronous command is still pending when Netbios returns to its caller, the return value is zero.

If the address specified by the pncb parameter is invalid, the return value is NRC_BADNCB.

If the buffer length specified in the ncb_length member of the NCB structure is incorrect, or if the buffer specified by the ncb_buffer member is protected from write operations, the return value is NRC_BUFLEN.

Remarks

When an asynchronous network control block finishes and the ncb_post member is nonzero, the routine specified in ncb_post is called with a single parameter of type PNCB. This parameter contains a pointer to the network control block.

The NCB structure also contains a handle of an event (the ncb_event member). The system sets the event to the nonsignaled state when an asynchronous NetBIOS command is accepted, and sets the event to the signaled state when the asynchronous NetBIOS command is completed. Only manual reset events should be used for synchronization. A specified event should not be associated with more than one active asynchronous NetBIOS command.

Using ncb_event to submit asynchronous requests requires fewer system resources than using ncb_post. Also, when ncb_event is nonzero, the pending request is canceled if the thread terminates before the request is processed. This is not true for requests sent by using ncb_post.

Win32s: This function does not support features that conflict with the non-preemptive, shared-memory design of Windows 3.1. Because the system does not implement events, this function ignores the ncb_event member of the NCB structure. Also, the system maintains one system-wide name table rather the a per-process name table.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.
Import Library: Use netapi32.lib.

See Also

The NetBIOS Interface Overview, NetBIOS Functions, NCB


NetBIOS Structures

The following structures are used in NetBIOS.

ACTION_HEADER
ADAPTER_STATUS
FIND_NAME_BUFFER
FIND_NAME_HEADER
LANA_ENUM
NAME_BUFFER
NCB
SESSION_BUFFER
SESSION_HEADER


ACTION_HEADER

The ACTION_HEADER structure contains information about an action. This action is an extension to the standard transport interface.

typedef struct _ACTION_HEADER {
    ULONG   transport_id;
    USHORT  action_code;
    USHORT  reserved;
} ACTION_HEADER;

Members

transport_id
Specifies the transport provider. This member can be used to check the validity of the request by the transport.

This member is always a four-character string. All strings starting with the letter M are reserved, as shown in the following example:
String | Meaning
M000 | All transports
MNBF | NBF
MABF | AsyBEUI
MXNS | XNS

action_code
Specifies the action.
reserved
Reserved.

Remarks

The scope of the action is determined by the ncb_lsn and ncb_num members of the NCB structure, as follows:

 | ncb_lsn = 0 | ncb_lsn != 0
ncb_num = 0 | Action applies to control channel associated with the valid LAN adapter. | Action applies to connection identifier associated with the valid local session number.
ncb_num != 0 | Action applies to address associated with the valid LAN adapter. | Illegal combination.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, NCB


ADAPTER_STATUS

The ADAPTER_STATUS structure contains information about a network adapter. This structure is pointed to by the ncb_buffer member of the NCB structure. ADAPTER_STATUS is followed by as many NAME_BUFFER structures as required to describe the network adapters on the system.

typedef struct _ADAPTER_STATUS { // adptst
    UCHAR   adapter_address[6];
    UCHAR   rev_major;
    UCHAR   reserved0;
    UCHAR   adapter_type;
    UCHAR   rev_minor;
    WORD    duration;
    WORD    frmr_recv;
    WORD    frmr_xmit;
    WORD    iframe_recv_err;
    WORD    xmit_aborts;
    DWORD   xmit_success;
    DWORD   recv_success;
    WORD    iframe_xmit_err;
    WORD    recv_buff_unavail;
    WORD    t1_timeouts;
    WORD    ti_timeouts;
    DWORD   reserved1;
    WORD    free_ncbs;
    WORD    max_cfg_ncbs;
    WORD    max_ncbs;
    WORD    xmit_buf_unavail;
    WORD    max_dgram_size;
    WORD    pending_sess;
    WORD    max_cfg_sess;
    WORD    max_sess;
    WORD    max_sess_pkt_size;
    WORD    name_count;
} ADAPTER_STATUS;

Members

adapter_address
Specifies encoded address of the adapter.
rev_major
Specifies the major software-release level. This value is 3 for IBM NetBIOS 3. x.
reserved0
Reserved. This value is always zero.
adapter_type
Specifies the adapter type. This value is 0xFF for a Token Ring adapter or 0xFE for an Ethernet adapter.
rev_minor
Specifies the minor software-release level. This value is zero for IBM NetBIOS x.0.
duration
Specifies the duration of the reporting period, in minutes.
frmr_recv
Specifies the number of FRMR frames received.
frmr_xmit
Specifies the number of FRMR frames transmitted.
iframe_recv_err
Specifies the number of I frames received in error.
xmit_aborts
Specifies the number of aborted transmissions.
xmit_success
Specifies the number of successfully transmitted packets.
recv_success
Specifies the number of successfully received packets.
iframe_xmit_err
Specifies the number of I frames transmitted in error.
recv_buff_unavail
Specifies the number of times a buffer was not available to service a request from a remote computer.
t1_timeouts
Specifies the number of times that the DLC T1 timer timed out.
ti_timeouts
Specifies the number of times that the ti inactivity timer timed out.The ti timer is used to detect links that have been broken.
reserved1
Reserved. This value is always zero.
free_ncbs
Specifies the current number of free network control blocks.
max_cfg_ncbs
Undefined for IBM NetBIOS 3.0.
max_ncbs
Undefined for IBM NetBIOS 3.0.
xmit_buf_unavail
Undefined for IBM NetBIOS 3.0.
max_dgram_size
Specifies the maximum size of a datagram packet. This value is always at least 512 bytes.
pending_sess
Specifies the number of pending sessions.
max_cfg_sess
Specifies the configured maximum pending sessions.
max_sess
Undefined for IBM NetBIOS 3.0.
max_sess_pkt_size
Specifies the maximum size of a session data packet.
name_count
Specifies the number of names in the local names table.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, NAME_BUFFER, NCB


FIND_NAME_BUFFER

The FIND_NAME_BUFFER structure contains information about a local network session. One or more FIND_NAME_BUFFER structures follows a FIND_NAME_HEADER structure when an application specifies the NCBFINDNAME command in the ncb_command member of the NCB structure.

typedef struct _FIND_NAME_BUFFER { // fnb
    UCHAR length;
    UCHAR access_control;
    UCHAR frame_control;
    UCHAR destination_addr[6];
    UCHAR source_addr[6];
    UCHAR routing_info[18];
} FIND_NAME_BUFFER;

Members

length
Specifies the length, in bytes, of the FIND_NAME_BUFFER structure. Although this structure always occupies 33 bytes, not all of the structure is necessarily valid.
access_control
Specifies the access control for the LAN header.
frame_control
Specifies the frame control for the LAN header.
destination_addr
Specifies the destination address of the remote node where the name was found.
source_addr
Specifies the source address for the remote node where the name was found.
routing_info
Specifies additional routing information.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, FIND_NAME_HEADER, NCB


FIND_NAME_HEADER

The FIND_NAME_HEADER structure contains information about a network name. This structure is followed by as many FIND_NAME_BUFFER structures as are required to describe the name.

typedef struct _FIND_NAME_HEADER { // fnh
    WORD  node_count;
    UCHAR reserved;
    UCHAR unique_group;
} FIND_NAME_HEADER;

Members

node_count
Specifies the number of nodes on which the specified name was found. This structure is followed by the number of FIND_NAME_BUFFER structures specified by the node_count member.
reserved
Reserved.
unique_group
Specifies whether the name is unique. This value is 0 to specify a unique name or 1 to specify a group.

Remarks

The FIND_NAME_HEADER structure is pointed to by the ncb_buffer member of the NCB structure when an application issues an NCBFINDNAME command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, FIND_NAME_BUFFER, NCB


LANA_ENUM

The LANA_ENUM structure contains the numbers for the current LAN adapters.

typedef struct _LANA_ENUM { // le
    UCHAR length;
    UCHAR lana[MAX_LANA];
} LANA_ENUM;

Members

length
Specifies the number of valid entries in the array of LAN adapter numbers.
lana
Specifies an array of LAN adapter numbers.

Remarks

The LANA_ENUM structure is pointed to by the ncb_buffer member of the NCB structure when an application issues the NCBENUM command. The NCBENUM command is not part of the IBM NetBIOS 3.0 specification.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, NCB


NAME_BUFFER

The NAME_BUFFER structure contains information about a local network name. One or more NAME_BUFFER structures follows an ADAPTER_STATUS structure when an application specifies the NCBASTAT command in the ncb_command member of the NCB structure.

typedef struct _NAME_BUFFER { // nb
    UCHAR name[NCBNAMSZ];
    UCHAR name_num;
    UCHAR name_flags;
} NAME_BUFFER;

Members

name
Specifies the local network name. This value is in the ncb_name member of the NCB structure.
name_num
Specifies the number for the local network name. This value is in the ncb_num member of the NCB structure.
name_flags
Specifies the current state of the name table entry. This member can be one of the following values:
Value | Meaning
REGISTERING | The name specified by the name member is being added to the network.
REGISTERED | The name specified by the name member has been successfully added to the network.
DEREGISTERED | The name specified by the name member has an active session when an NCBDELNAME command is issued. The name will be removed from the name table when the session is closed.
DUPLICATE | A duplicate name was detected during registration.
DUPLICATE_DEREG | A duplicate name was detected with a pending deregistration.
GROUP_NAME | The name specified by the name member was created by using the NCBADDGRNAME command.
UNIQUE_NAME | The name specified by the name member was created by using the NCBADDNAME command.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, ADAPTER_STATUS, NCB


NCB

The NCB structure represents a network control block. It contains information about the command to perform, an optional post routine, an optional event handle, and a pointer to a buffer that is used for messages or other data. A pointer to this structure is passed to the Netbios function.

typedef struct _NCB { // ncb
    UCHAR  ncb_command;
    UCHAR  ncb_retcode;
    UCHAR  ncb_lsn;
    UCHAR  ncb_num;
    PUCHAR ncb_buffer;
    WORD   ncb_length;
    UCHAR  ncb_callname[NCBNAMSZ];
    UCHAR  ncb_name[NCBNAMSZ];
    UCHAR  ncb_rto;
    UCHAR  ncb_sto;
    void (*ncb_post) (struct _NCB *);
    UCHAR  ncb_lana_num;
    UCHAR  ncb_cmd_cplt;
    UCHAR  ncb_reserve[10];
    HANDLE ncb_event;
} NCB;

Members

ncb_command
Specifies the command code and a flag that indicates whether the NCB structure is processed asynchronously. The most significant bit contains the flag. If the ASYNCH constant is combined with a command code (by using the OR operator), the NCB structure is processed asynchronously. The following command codes are supported.
Code | Meaning
NCBACTION Windows NT: Enables extensions to the transport interface. NCBACTION is mapped to TdiAction. When this code is specified, the ncb_buffer member points to a buffer to be filled with an ACTION_HEADER structure, which is optionally followed by data. NCBACTION commands cannot be canceled by using NCBCANCEL.

NCBACTION is not a standard NetBIOS 3.0 command.

NCBADDGRNAME | Adds a group name to the local name table. This name cannot be used by another process on the network as a unique name, but it can be added by anyone as a group name.
NCBADDNAME | Adds a unique name to the local name table. The TDI driver ensures that the name is unique across the network.
NCBASTAT | Retrieves the status of either a local or remote adapter. When this code is specified, the ncb_buffer member points to a buffer to be filled with an ADAPTER_STATUS structure, followed by an array of NAME_BUFFER structures.
NCBCALL | Opens a session with another name.
NCBCANCEL | Cancels a previous pending command.
NCBCHAINSEND | Sends the contents of two data buffers to the specified session partner.
NCBCHAINSENDNA | Sends the contents of two data buffers to the specified session partner and does not wait for acknowledgment.
NCBDELNAME | Deletes a name from the local name table.
NCBDGRECV | Receives a datagram from any name.
NCBDGRECVBC | Receives a broadcast datagram from any name.
NCBDGSEND | Sends datagram to a specified name.
NCBDGSENDBC | Sends a broadcast datagram to every host on the local area network (LAN).
NCBENUM Windows NT: Enumerates LAN adapter (LANA) numbers. When this code is specified, the ncb_buffer member points to a buffer to be filled with a LANA_ENUM structure.

NCBENUM is not a standard NetBIOS 3.0 command.

NCBFINDNAME | Determines the location of a name on the network. When this code is specified, the ncb_buffer member points to a buffer to be filled with a FIND_NAME_HEADER structure followed by one or more FIND_NAME_BUFFER structures.
NCBHANGUP | Closes a specified session.
NCBLANSTALERT | Windows NT: Notifies the user of LAN failures that last for more than one minute.
NCBLISTEN | Enables a session to be opened with another name (local or remote).
NCBRECV | Receives data from the specified session partner.
NCBRECVANY | Receives data from any session corresponding to a specified name.
NCBRESET | Resets a LAN adapter. An adapter must be reset before it can accept any other NCB command that specifies the same number in the ncb_lana_num member.
Use the following values to specify how resources are to be freed:
  • If ncb_lsn is not 0x00, all resources associated with ncb_lana_num are to be freed.
  • If ncb_lsn is 0x00, all resources associated with ncb_lana_num are to be freed, and new resources are to be allocated. The ncb_callname[0] byte specifies the maximum number of sessions, and the ncb_callname[2] byte specifies the maximum number of names. A nonzero value for the ncb_callname[3] byte requests that the application use NAME_NUMBER_1.
NCBSEND | Sends data to the specified session partner.
NCBSENDNA | Sends data to specified session partner and does not wait for acknowledgment.
NCBSSTAT | Retrieves the status of the session. When this value is specified, the ncb_buffer member points to a buffer to be filled with a SESSION_HEADER structure, followed by one or more SESSION_BUFFER structures.
NCBTRACE Activates or deactivates NCB tracing.

This command is not supported.

NCBUNLINK Unlinks the adapter.

This command is provided for compatibility with earlier versions of NetBIOS. It has no effect in Win32.

ncb_retcode
Specifies the return code. This value is set to NRC_PENDING while an asynchronous operation is in progress. The system returns one of the following values:
Value | Meaning
NRC_GOODRET | The operation succeeded.
NRC_BUFLEN | An illegal buffer length was supplied.
NRC_ILLCMD | An illegal command was supplied.
NRC_CMDTMO | The command was timed out.
NRC_INCOMP | The message was incomplete. The application is to issue another command.
NRC_BADDR | The buffer address was illegal.
NRC_SNUMOUT | The session number was out of range.
NRC_NORES | No resource was available.
NRC_SCLOSED | The session was closed.
NRC_CMDCAN | The command was canceled.
NRC_DUPNAME | A duplicate name existed in the local name table.
NRC_NAMTFUL | The name table was full.
NRC_ACTSES | The command finished; the name has active sessions and is no longer registered.
NRC_LOCTFUL | The local session table was full.
NRC_REMTFUL | The remote session table was full. The request to open a session was rejected.
NRC_ILLNN | An illegal name number was specified.
NRC_NOCALL | The system did not find the name that was called.
NRC_NOWILD | Wildcards are not permitted in the ncb_name member.
NRC_INUSE | The name was already in use on the remote adapter.
NRC_NAMERR | The name was deleted.
NRC_SABORT | The session ended abnormally.
NRC_NAMCONF | A name conflict was detected.
NRC_IFBUSY | The interface was busy.
NRC_TOOMANY | Too many commands were outstanding; the application can retry the command later.
NRC_BRIDGE | The ncb_lana_num member did not specify a valid network number.
NRC_CANOCCR | The command finished while a cancel operation was occurring.
NRC_CANCEL | The NCBCANCEL command was not valid; the command was not canceled.
NRC_DUPENV | The name was defined by another local process.
NRC_ENVNOTDEF | The environment was not defined. A reset command must be issued.
NRC_OSRESNOTAV | Operating system resources were exhausted. The application can retry the command later.
NRC_MAXAPPS | The maximum number of applications was exceeded.
NRC_NOSAPS | No service access points (SAPs) were available for NetBIOS.
NRC_NORESOURCES | The requested resources were not available.
NRC_INVADDRESS | The NCB address was not valid.
This return code is not part of the IBM NetBIOS 3.0 specification and is not returned in the NCB structure. Instead, it is returned by Netbios.
NRC_INVDDID | The NCB DDID was invalid.
NRC_LOCKFAIL | The attempt to lock the user area failed.
NRC_OPENERR | An error occurred during an open operation being performed by the device driver. This error code is not part of the NetBIOS 3.0 specification.
NRC_SYSTEM | A system error occurred.
NRC_PENDING | An asynchronous operation is not yet finished.

ncb_lsn
Identifies the local session number. This number uniquely identifies a session within an environment. This number is returned by Netbios after a successful NCBCALL command.
ncb_num
Specifies the number for the local network name. This number is returned by Netbios after a successful NCBADDNAME or NCBADDGRNAME command. This number, not the name, must be used with all datagram commands and for NCBRECVANY commands.

The number for NAME_NUMBER_1 is always 0x01. Netbios assigns values in the range 0x02 to 0xFE for the remaining names.

ncb_buffer
Pointer to the message buffer. The buffer must have write access. Its uses are as follows:
Command | Purpose
NCBSEND | Contains the message to be sent.
NCBRECV | Receives the message.
NCBSSTAT | Receives the requested status information.

ncb_length
Specifies the size, in bytes, of the message buffer. For receive commands, this member is set by the Netbios function to indicate the number of bytes received.

If the buffer length is incorrect, the Netbios function returns the NRC_BUFLEN error code.

ncb_callname
Specifies the name of the remote application. Trailing-space characters should be supplied to make the length of the string equal to NCBNAMSZ.
ncb_name
Specifies the name by which the application is known. Trailing-space characters should be supplied to make the length of the string equal to NCBNAMSZ.
ncb_rto
Specifies the time-out period for receive operations, in 500-millisecond units, for the session. A value of zero implies no time-out. Specify with the NCBCALL or NCBLISTEN command. Affects subsequent NCBRECV commands.
ncb_sto
Specifies the time-out period for send operations, in 500-millisecond units, for the session. A value of zero implies no time-out. Specify with the NCBCALL or NCBLISTEN command. Affects subsequent NCBSEND and NCBCHAINSEND commands.
ncb_post
Specifies the address of the post routine to call when the asynchronous command is completed. The post routine is defined as:

NCB_POST PostRoutine( PNCB pncb );

where the pncb parameter is a pointer to the completed network control block.

ncb_lana_num
Specifies the LAN adapter number. This zero-based number corresponds to a particular transport provider using a particular LAN adapter board.
ncb_cmd_cplt
Specifies the command complete flag. This value is the same as the ncb_retcode member.
ncb_reserve
Reserved; must be zero.
ncb_event
Specifies a handle to an event object that is set to the nonsignaled state when an asynchronous command is accepted, and it is set to the signaled state when the asynchronous command is completed. The event is signaled if the Netbios function returns a nonzero value. Only manual reset events should be used for synchronization. A specified event should not be associated with more than one active asynchronous command.

The ncb_event member must be zero if the ncb_command member does not have the ASYNCH flag set or if ncb_post is nonzero. Otherwise, Netbios returns the NRC_ILLCMD error code.

Remarks

Using ncb_event to issue asynchronous requests requires fewer system resources than using ncb_post. In addition, when ncb_event is nonzero, the pending request is canceled if the thread terminates before the request is processed. This is not true for asynchronous requests sent using ncb_post.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, ACTION_HEADER, ADAPTER_STATUS, FIND_NAME_BUFFER, FIND_NAME_HEADER, LANA_ENUM, NAME_BUFFER, Netbios, SESSION_BUFFER, SESSION_HEADER


SESSION_BUFFER

The SESSION_BUFFER structure contains information about a local network session. One or more SESSION_BUFFER structures follows a SESSION_HEADER structure when an application specifies the NCBSSTAT command in the ncb_command member of the NCB structure.

typedef struct _SESSION_BUFFER { // sb
    UCHAR lsn;
    UCHAR state;
    UCHAR local_name[NCBNAMSZ];
    UCHAR remote_name[NCBNAMSZ];
    UCHAR rcvs_outstanding;
    UCHAR sends_outstanding;
} SESSION_BUFFER;

Members

lsn
Specifies the local session number.
state
Specifies the state of the session. This member can be one of the following values:
Value | Meaning
LISTEN_OUTSTANDING | The session is waiting for a call from a remote computer.
CALL_PENDING | The session is attempting to connect to a remote computer.
SESSION_ESTABLISHED | The session connected and is able to transfer data.
HANGUP_PENDING | The session is being deleted due to a command by the local user.
HANGUP_COMPLETE | The session was deleted due to a command by the local user.
SESSION_ABORTED | The session was abandoned due to a network or user problem.

local_name
Specifies the 16-byte NetBIOS name on the local computer used for this session.
remote_name
Specifies the 16-byte NetBIOS name on the remote computer used for this session.
rcvs_outstanding
Specifies the number of pending NCBRECV commands.
sends_outstanding
Specifies the number of pending NCBSEND and NCBCHAINSEND commands.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, NCB, SESSION_HEADER


SESSION_HEADER

The SESSION_HEADER structure contains information about a network session. This structure is pointed to by the ncb_buffer member of the NCB structure. SESSION_HEADER is followed by as many SESSION_BUFFER structures as are required to describe the current network sessions.

typedef struct _SESSION_HEADER { // sh
    UCHAR sess_name;
    UCHAR num_sess;
    UCHAR rcv_dg_outstanding;
    UCHAR rcv_any_outstanding;
} SESSION_HEADER;

Members

sess_name
Specifies the name number of the session. This value corresponds to the ncb_num member of the NCB structure.
num_sess
Specifies the number of sessions that have the name specified by the sess_name member.
rcv_dg_outstanding
Specifies the number of outstanding NCBDGRECV and NCBDGRECVBC commands.
rcv_any_outstanding
Specifies the number of outstanding NCBRECVANY commands.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in nb30.h.

See Also

The NetBIOS Interface Overview, NetBIOS Structures, NCB, SESSION_BUFFER


Network Dynamic Data Exchange

The Win32 API provides network dynamic data exchange (network DDE) functions to enable a process to establish conversations with processes running on different computers in a network.


About Network DDE

Network DDE is used to initiate and maintain the network connections needed for DDE conversations between applications running on different computers in a network. A DDE conversation is the interaction between client and server applications. You use network DDE along with DDE and the DDE management library (DDEML) in your application.

DDE is a form of interprocess communication that uses shared memory to exchange data between applications. Applications can use DDE for one time data transfers or for ongoing exchanges and updating data. For more information on DDE, see Dynamic Data Exchange.

DDEML simplifies the task of adding DDE capability to a Win32-based application. Instead of sending, posting, and processing DDE messages directly, an application uses the functions provided by the DDEML to manage DDE conversations. For more information on DDEML, see Dynamic Data Exchange Management Library.

Network DDE Files

To use the API elements of network DDE, you must include the NDDEAPI.H header file in your source files and include NDDEAPI.LIB file on your link line. You must also make sure that the NDDEAPI.DLL file is loaded.

Windows 95: Windows 95 includes a 16-bit NDDEAPI.DLL. However, Windows 95 does not include a 32-bit NDDEAPI.DLL. Therefore, on Windows 95, Win32-based applications that use network DDE functions need to thunk to the functions in the 16-bit NDDEAPI.DLL.

Win32s: The network DDE functions are not supported. Therefore, you will need to either use the DDESHARE utility or thunk to the functions in the NDDEAPI.DLL provided with Windows for Workgroups.


Network DDE Agent

The network DDE agent starts network DDE if it detects local network DDE activity. It does not detect a remote client trying to connect. Therefore, before any client can successfully connect, network DDE must be started on the server computer. Note that network DDE is not started by default. To start network DDE, run NETDDE.EXE. This file is located in your Windows directory.

The network DDE agent also starts the applications necessary for network DDE. After network DDE is started, DDE conversations are controlled through a network DDE window associated with one of the network DDE applications. This application acts as a proxy. It communicates with all local and remote DDE applications.


DDE Shares

DDE shares are a machine resource. They are similar to file shares because they are used to control access to a resource. With file shares, the resource is a file. With DDE shares, the resource is dynamically exchanged data. The type of data exchanged is determined by the server application that supplies the data and the client application that requests the data.

The server calls the NDdeShareAdd function to create the DDE share, which is stored in the DDE share database manager (DSDM).

The client starts the DDE conversation by connecting to the DDE share. The client must call the DdeInitialize function to initialize DDEML and call the DdeConnect function to connect to the DDE share. In the DdeConnect call, the client specifies the service name

\\<ComputerName>\NDDE$

where <ComputerName> is the name of the computer running the server application. The NDDE$ indicates that the topic provided to DdeConnect is the DDE share name on the remote computer named <ComputerName>.

There are three types of DDE shares: old style, new style, and static. It is typical to support only the static type. The names of static shares follow the convention <ShareName>$.


Trusted Shares and Security

Trusted Shares

When a client user connects to a DDE share from a remote computer, network DDE accepts the request only if the following statements are true:

  • The user who created the share has granted trusted status to the share by calling NDdeSetTrustedShare. Only the creator of the share can grant trusted status to the share. Not even an administrator can grant trusted status to a DDE share that was created by a different user.
  • The user who created the share is currently logged on to the server computer.

The process of granting trusted status to a share adds the share to the logged-on user's trusted shares list in the DSDM. This creates a trust relationship between the server and its clients. Once a DDE share has trusted status, clients can connect to it as long as the user that created the share is logged on. When the client connects to the share from a remote computer, network DDE accepts the request only if the share is listed in the logged-on user's trusted shares list in the DSDM.

Security

Network DDE performs an additional security check when the client requests data or a link. It checks that the server has granted the remote user the necessary permission for the operation. The server controls access to the share through the pSD parameter of the NDdeShareAdd function. This parameter specifies the security descriptor. If this parameter is NULL, the function creates a default security descriptor that grants full access to the creator of the share and grants read and link permission to all other users. To grant or deny additional permissions to individual users or groups of users, create and use a security descriptor. For more information on security descriptors, see Access Control.

To obtain the security descriptor for an existing DDE share, call the NDdeGetShareSecurity function. You can edit the information and then update the security descriptor for the share by using the NDdeSetShareSecurity function.


Managing DDE Shares

Network DDE provides functions that allow you to delete a share, get or set share information, or enumerate shares.

  • Deleting a DDE Share A server can remove a DDE share by using the NDdeShareDel function.
  • Getting and Setting DDE Share Information You can retrieve information about a DDE share by using the NDdeShareGetInfo function. You can also change information about the share by using the NDdeShareSetInfo function.
  • Enumerating DDE Shares You can enumerate the existing DDE shares for a computer by using the NDdeShareEnum function. You can enumerate the trusted DDE shares by using the NDdeTrustedShareEnum function.

    You can enumerate the users connected to your DDE shares by using the NetSessionEnum function.

  • Changing the DDE Share Name To change the name of a DDE share, an application must delete the old share and create a new share.
To change the share name
  1. Retrieve the share information using NDdeShareGetInfo.
  2. Remove the share using NDdeShareDel.
  3. Change the lpszShareName member of the NDDESHAREINFO structure returned by NDdeShareGetInfo.
  4. Pass the modified NDDESHAREINFO structure to NDdeShareAdd.


Using Network DDE

The examples in this section demonstrate the following tasks:

  • Creating a DDE share
  • Granting trusted status to a DDE share
  • Establishing a network DDE conversation
  • Displaying errors to the user


Creating a DDE Share

The following topics describe two methods for creating DDE shares:

  • Using NDdeShareAdd to Create a DDE Share
  • Using DDESHARE to Create a DDE Share

Your server application should use NDdeShareAdd to create a DDE share. However, you may wish to use DDESHARE on Win32s instead of thunking to the 16-bit NDdeShareAdd.


Using NDdeShareAdd to Create a DDE Share

The NDdeShareAdd function is used by a DDE server application to create a DDE share.

Before creating a DDE share, it is a good idea to verify that the proposed share name and topic name are valid by using the NDdeIsValidShareName and NDdeIsValidAppTopicList functions. These functions are also called by NDdeShareAdd.

The following example demonstrates how to create a DDE share. It uses a NULL discretionary access control list (DACL) to grant write access to all users. Note that this is not the same as specifying NULL in the pSD parameter of NDdeShareAdd.

BOOL MyCreateDdeShare( LPTSTR lpszShareName, LPTSTR lpszTopicList )
{
   NDDESHAREINFO ndsi;
   PSECURITY_DESCRIPTOR pSD = NULL;

// Where lpszShareName is the share name.
   if( NDdeIsValidShareName( lpszShareName ) == FALSE )
      return FALSE;

// Where lpszTopicList is a list of null-terminated strings terminated
// by another null character.
   if( NDdeIsValidAppTopicList( lpszTopicList ) == FALSE )
      return FALSE;

// Fill in the NDDESHAREINFO structure.
   ndsi.lRevision = 1;
   ndsi.lpszShareName = lpszShareName;
   ndsi.lShareType = SHARE_TYPE_STATIC;
   ndsi.lpszAppTopicList = lpszTopicList;
   ndsi.fSharedFlag = TRUE;
   ndsi.fService = FALSE;
   ndsi.fStartAppFlag = TRUE;
   ndsi.nCmdShow = SW_SHOWNORMAL;
   ndsi.cNumItems = 0;
   ndsi.lpszItemList = "";

// Create a security descriptor to allow write access.
   pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(
                                   LPTR,
                                   SECURITY_DESCRIPTOR_MIN_LENGTH );
   InitializeSecurityDescriptor( pSD, SECURITY_DESCRIPTOR_REVISION );
   SetSecurityDescriptorDacl( pSD, TRUE, (PACL)NULL, FALSE );

// Delete possible old DDE share.
   NDdeShareDel(
      NULL,
      lpszShareName,
      0
     );

// Create the DDE share.
   NDdeShareAdd(
      NULL,
      2,
      pSD,
      (LPBYTE)&ndsi,
      sizeof(NDDESHAREINFO)
     );

   LocalFree( pSD );
   return TRUE;
}

The following example shows how you could call the MyCreateDdeShare function to create the share MyDdeShare$:

char *TopicList = "\0\0MyApp|MyTopic\0\0";

MyCreateDdeShare( "MyDdeShare$", TopicList );

This share name ends with a dollar sign ($), indicating that it is a static DDE share. Topic strings are provided only for the static-type DDE share.


Using DDESHARE to Create a DDE Share

Windows for Workgroups and Windows NT provide the DDESHARE utility so that users can manage DDE shares. To run DDESHARE, go to File Manager, locate DDESHARE.EXE, and start the application.

To create a DDE share
  1. On the Shares menu, click DDE Shares. DDESHARE displays the following dialog box:

  2. Click the Add a Share button. DDESHARE displays the following dialog box:

  3. Fill in the Share Name, Application Name, and Topic Name text boxes, then click OK.


Granting Trusted Status To a DDE Share

The following topics describe two methods for granting trusted status to DDE shares:

  • Using NDdeSetTrustedShare to Grant Trusted Status
  • Using DDESHARE to Grant Trusted Status

Your server application should use NDdeSetTrustedShare to grant trusted status to a DDE share. However, you may wish to use DDESHARE on Win32s instead of thunking to the 16-bit NDdeSetTrustedShare.


Using NDdeSetTrustedShare to Grant Trusted Status

The NDdeSetTrustedShare function is used by a DDE server to grant trusted status to a DDE share.

The following example demonstrates how to grant trusted status to a DDE share:

BOOL MyTrustShare( LPSTR lpszShareName )
{
// Grant trusted status.
   if( NDdeSetTrustedShare( NULL, lpszShareName,
         NDDE_TRUST_SHARE_INIT | NDDE_TRUST_SHARE_START
   ) == NDDE_NO_ERROR )
      return TRUE;
   else return FALSE;
}

The following example shows how you could call the MyTrustShare function to grant trusted status to the existing share MyDdeShare$:

MyTrustShare( "MyDdeShare$" );


Using DDESHARE to Grant Trusted Status

Windows for Workgroups and Windows NT provide the DDESHARE utility so that users can manage DDE shares. To run DDESHARE, go to File Manager, locate DDESHARE.EXE, and start the application.

To grant trusted status
  1. On the Shares menu, click DDE Shares. DDESHARE displays the following dialog box:

  2. Click the Trust Share button. DDESHARE displays the following dialog box:

  3. Choose the options you want, click the Set button, and then click OK.


Establishing a Network DDE Conversation

Establishing a conversation between a client application and a server application on different computers is similar to establishing a conversation between a client and server on the same computer. The difference is that the client specifies a computer and a DDE share, rather than an application and a topic.

The first step is for the server to register with the DDEML by calling the DdeInitialize function. This call requires a pointer to the application-defined DDE callback function DdeCallback. The server also registers the service name that the DDE server supports by calling the DdeNameService function.

DWORD g_idInst;

BOOL MyDdeShareInit( LPTSTR lpszServer, PFNCALLBACK DdeCallback )
{
   HSZ hszService;
   char ServerBuf[MAX_COMPUTERNAME_LENGTH+8];

// Register the server application.
   if( DdeInitialize(
      &g_idInst,
      (PFNCALLBACK) DdeCallback,
      APPCLASS_STANDARD | CBF_FAIL_SELFCONNECTIONS |
      CBF_FAIL_REQUESTS | CBF_FAIL_EXECUTES,
      0L
   ) != DMLERR_NO_ERROR )
      return FALSE;

// Check if "\\server" or just "server" is specified.
   if( lpszServer[0] == '\\' )
      wsprintf( ServerBuf, "%s\\NDDE$", lpszServer );
   else wsprintf( ServerBuf, "\\\\%s\\NDDE$", lpszServer );

// Register the service names.
   hszService = DdeCreateStringHandle( g_idInst, ServerBuf, 0 );
   DdeNameService(
      g_idInst,
      hszService,
      0,
      DNS_REGISTER
     );

   DdeFreeStringHandle( g_idInst, hszService );
   return TRUE;
}

The following example shows how you could call the MyConnect function to initialize DDEML for the server application on computer ServerA:

// Application-supplied callback function.
HDDEDATA CALLBACK DdeCallback( UINT iType, UINT iFmt, HCONV hConv,
   HSZ hsz1, HSZ hsz2, HDDEDATA hData, DWORD dwData1, DWORD dwData2 )
{
   switch( iType )
   {
      case XTYP_CONNECT:
      // Validate topic for connection.
         ...
         return (HDDEDATA) TRUE;
      ...
      default:
         return (HDDEDATA) 0;
   }
}

MyDdeShareInit( "ServerA", DdeCallback );

As with any DDE conversation, the client and server applications must cooperate to establish a conversation. For network DDE, the client must have the computer name and the share name. The client then uses the DdeConnect function to establish a network DDE conversation.

HCONV g_hConv;

BOOL MyConnect( LPSTR lpszServer, LPTSTR lpszTopic )
{
   HSZ hszServer, hszTopic;
   char ServerBuf[MAX_COMPUTERNAME_LENGTH+8];

// Register the client application.
   if( DdeInitialize(
      &g_idInst,
      (PFNCALLBACK) DdeCallback,
      APPCLASS_STANDARD | CBF_FAIL_SELFCONNECTIONS |
      CBF_FAIL_REQUESTS | CBF_FAIL_EXECUTES,
      0L
   ) != DMLERR_NO_ERROR )
      return FALSE;

// Check if "\\server" or just "server" is specified.
   if( lpszServer[0] == '\\' )
      wsprintf( ServerBuf, "%s\\NDDE$", lpszServer );
   else wsprintf( ServerBuf, "\\\\%s\\NDDE$", lpszServer );

   hszServer = DdeCreateStringHandle(g_idInst, ServerBuf, 0);
   hszTopic = DdeCreateStringHandle(g_idInst, lpszTopic, 0);

   if( (g_hConv = DdeConnect(g_idInst,
      hszServer,
      hszTopic,
      NULL )
   ) == 0 )
      return FALSE;

   DdeFreeStringHandle( g_idInst, hszServer );
   DdeFreeStringHandle( g_idInst, hszTopic );
   return TRUE;
}

The following example shows how you could call this function to connect to the DDE share MyDdeShare$ on computer ServerA:

// Application-supplied callback function.
HDDEDATA CALLBACK DdeCallback( UINT iType, UINT iFmt, HCONV hConv,
   HSZ hsz1, HSZ hsz2, HDDEDATA hData, DWORD dwData1, DWORD dwData2 )
{
   switch( iType )
   {
      ...
      default:
         return (HDDEDATA) 0;
   }
}

MyConnect( "ServerA", "MyDdeShare$" );


Displaying Errors to the User

Whenever a network DDE function returns an error value, you can retrieve an error message suitable for displaying to a user by using the NDdeGetErrorString function.

DisplayNDdeErrorString( UINT uCode, LPTSTR lpszTitle )
{
   char buf[256];

   NDdeGetErrorString(
      uCode,
      buf,
      sizeof(buf)
     );
   MessageBox( NULL, buf, lpszTitle, MB_ICONEXCLAMATION | MB_OK );
}


Network DDE Reference

This following elements are used with network DDE.

  • Network DDE Functions
  • Network DDE Structures


Network DDE Functions

The following functions are used with network DDE.

NDdeGetErrorString
NDdeGetShareSecurity
NDdeGetTrustedShare
NDdeIsValidAppTopicList
NDdeIsValidShareName
NDdeSetShareSecurity
NDdeSetTrustedShare
NDdeShareAdd
NDdeShareDel
NDdeShareEnum
NDdeShareGetInfo
NDdeShareSetInfo
NDdeTrustedShareEnum


NDdeGetErrorString

The NDdeGetErrorString function is called to convert an error code returned by a network DDE function into an error string that explains the returned error code.

UINT NDdeGetErrorString(
  UINT uErrorCode,         // error code to get string for
  LPTSTR lpszErrorString,  // buffer to hold error string
  DWORD cBufSize           // size of buffer
);

Parameters

uErrorCode
Error code to be converted into an error string.
lpszErrorString
Address of a buffer to accept the translated error string. This parameter must not be NULL. If the buffer is not large enough to store the complete error string, the string is truncated.
cBufSize
The size of the buffer allocated to receive the error string, in bytes.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code. If the lpszErrorString buffer is not large enough to accept the complete error string, and the string is truncated, the function returns the value NDDE_BUF_TOO_SMALL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions


NDdeGetShareSecurity

The NDdeGetShareSecurity function is called to get the SECURITY_DESCRIPTOR associated with the DDE share. This is done usually for editing.

UINT NDdeGetShareSecurity(
  LPTSTR lpszServer,        // server to execute on
  LPTSTR lpszShareName,     // name of share to delete
  SECURITY_INFORMATION si,  // requested information
  PSECURITY_DESCRIPTOR pSD, // address of SD buffer
  DWORD cbSD,               // size of SD buffer
  LPDWORD lpcbsdRequired    // address of required size for SD buffer
);

Parameters

lpszServer
Address of the server name on which the DSDM resides.
lpszShareName
Address of the share name whose security descriptor is to be retrieved from the DSDM. This parameter must not be NULL.
si
Identifies the SECURITY_INFORMATION to be retrieved from the SECURITY_DESCRIPTOR associated with the share.
pSD
Address of a buffer that will accept the retrieved self-relative SECURITY_DESCRIPTOR. This parameter can be NULL. If this parameter is NULL, the DSDM determines the size of the requested security information and returns the number of bytes needed in the lpcbsdRequired parameter along with the NDDE_BUF_TOO_SMALL error code.
cbSD
Specifies the size of the buffer provided and referenced by the pSD parameter to accept the retrieved security descriptor. It must be 0 if pSD is NULL.
lpcbsdRequired
Address of the variable into which the actual size of the retrieved security descriptor is stored. This paramter must not be NULL.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the pSD parameter was NULL, it returns NDDE_BUF_TOO_SMALL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions, SECURITY_INFORMATION, NDdeSetShareSecurity


NDdeGetTrustedShare

The NDdeGetTrustedShare function is called to retrieve the options associated with a DDE share that is in the server user's list of trusted shares.

UINT NDdeGetTrustedShare(
  LPTSTR lpszServer,        // server to execute on
  LPTSTR lpszShareName,     // name of share to query
  LPDWORD lpdwTrustOptions, // trust options in effect
  LPDWORD lpdwShareModId0,  // first word of share modify identifier
  LPDWORD lpdwShareModId1   // second word of share modify identifier
);

Parameters

lpszServer
Address of the server name on which the DSDM resides.
lpszShareName
Address of the share name whose trusted status is being queried. This parameter must not be NULL.
lpdwTrustOptions
Address of a variable into which the TRUST_SHARE_OPTIONS will be stored. This parameter must not be NULL.
lpdwShareModId0
Address of a variable into which the first word of the trusted share modify identifier will be stored. This parameter must not be NULL.
lpdwShareModId1
Address of a variable into which the second word of the trusted share modify identifier will be stored. This parameter must not be NULL.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

The trusted share modify identifier reflects the version of the DDE share in the DSDM at the time the DDE share was initially granted trusted status. The trusted share modify identifier is primarily used to purge obsolete trusted shares. However, the user does not need to purge obsolete trusted shares. The network DDE agent purges obsolete shares on the user's behalf.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDdeSetTrustedShare


NDdeIsValidAppTopicList

The NDdeIsValidAppTopicList function is called to check an application and topic string ("AppName|TopicName") for proper syntax.

BOOL NDdeIsValidAppTopicList(
  LPTSTR targetTopic     // points to app and topic string
);

Parameters

targetTopic
Address of the application and topic string to validate. This parameter must not be NULL.

Return Values

If the targetTopic parameter has valid syntax, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

This function is also called by NDdeShareAdd when it creates the DDE share.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDdeShareAdd


NDdeIsValidShareName

The NDdeIsValidShareName function is called to check a share name for proper syntax.

BOOL NDdeIsValidShareName(
  LPTSTR shareName   // points to share name to validate
);

Parameters

shareName
Address of a share name to validate. This parameter must not be NULL.

Return Values

If the share name has valid syntax, the return value is nonzero.

If the share name does not have valid syntax, the return value is zero.

Remarks

This function is also called by NDdeShareAdd when it creates the DDE share.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDdeShareAdd


NDdeSetShareSecurity

The NDdeSetShareSecurity function is called to set the SECURITY_DESCRIPTOR associated with the DDE share. This is done usually after editing the DACL assigned to the DDE share.

UINT NDdeSetShareSecurity(
  LPTSTR lpszServer,         // server to execute on
  LPTSTR lpszShareName,      // name of share to delete
  SECURITY_INFORMATION si,   // type of information
  PSECURITY_DESCRIPTOR pSD   // address of security descriptor to set
);

Parameters

lpszServer
Address of the server name on which the DSDM will be modified.
lpszShareName
Address of the share name whose security descriptor is to be modified in the DSDM. This parameter must not be NULL.
si
Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the pSD parameter.
pSD
Address of the SECURITY_DESCRIPTOR that will be the source of the security information modified in the DDE share. This parameter must not be NULL and should point to a valid security descriptor.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

To modify the SECURITY_DESCRIPTOR associated with a DDE share in the DSDM, the user must have appropriate privilege; the share creator has this privilege.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions, SECURITY_INFORMATION, NDdeGetShareSecurity


NDdeSetTrustedShare

The NDdeSetTrustedShare function is called to grant the referenced DDE share trusted status within the current user's context.

UINT NDdeSetTrustedShare(
  LPTSTR lpszServer,     // server to execute on
  LPTSTR lpszShareName,  // name of share to delete
  DWORD dwTrustOptions   // trust options to apply
);

Parameters

lpszServer
Address of the server name on which the DSDM will be modified.
lpszShareName
Address of the share name being granted trusted status. This parameter must not be NULL.
dwTrustOptions
Specifies the options affecting the trusted status of the DDE share. The following TRUST_SHARE_OPTIONS options are available:
Option | Meaning
NDDE_TRUST_SHARE_START | Allow the application to be started in the user's context.
NDDE_TRUST_SHARE_INIT | Allow a client to initiate to the application if it is already running in the user's context.
NDDE_TRUST_SHARE_DEL | Remove the share's trusted status.
NDDE_TRUST_CMD_SHOW | Start the application with CmdShow field defined here overriding the CmdShow specified in the DDE share DSDM.
NDDE_CMD_SHOW_MASK | CmdShow value used to override the DDE share CmdShow if the NDDE_TRUST_CMD_SHOW is set.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

The DDE share must first be created with NDdeShareAdd.

If NDdeSetTrustedShare is called with dwTrustOptions set to 0, the trusted share loses its trusted status.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDdeShareAdd


NDdeShareAdd

The NDdeShareAdd function is called to create and add a new DDE share to the DDE Share Database Manager (DSDM).

UINT NDdeShareAdd(
  LPTSTR lpszServer,         // server to execute on
  UINT nLevel,               // info level must be 2
  PSECURITY_DESCRIPTOR pSD,  // initial security descriptor
  LPBYTE lpBuffer,           // address of NDDESHAREINFO
  DWORD cBufSize             // size of supplied buffer
);

Parameters

lpszServer
Address of the server name on which the DSDM will be modified.
nLevel
Must always be 2.
pSD
Address of the SECURITY_DESCRIPTOR that will be associated with this share and against which access checks will be performed on subsequent initiates to this share. This parameter can optionally be NULL, in which case the DSDM creates a default SECURITY_DESCRIPTOR that grants "Full Control" to the CREATOR_OWNER and "Read and Link" to everyone.
lpBuffer
Address of the NDDESHAREINFO structure that defines the ApplicationTopic list associated with the DDE share being created as well as other parameters. This parameter must not be NULL.
cBufSize
Size of the structure identified by lpBuffer. This parameter must not be 0.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

Before a client can connect to the DDE share, it must be trusted with NDdeSetTrustedShare.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDDESHAREINFO, NDdeSetTrustedShare


NDdeShareDel

The NDdeShareDel function is called to delete a DDE share from the DSDM.

UINT NDdeShareDel(
  LPTSTR lpszServer,     // server to execute on
  LPTSTR lpszShareName,  // name of share to delete
  UINT wReserved         // must be 0
);

Parameters

lpszServer
Address of the server name on which the DSDM will be modified.
lpszShareName
Address of the share name that is to be deleted from the DSDM. This parameter must not be NULL.
wReserved
This parameter must be 0.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

To delete a DDE share from the DSDM, you must have the appropriate privilege. The share creator has delete privilege.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions


NDdeShareEnum

The NDdeShareEnum function is called to list the available DDE shares in the DSDM.

UINT NDdeShareEnum(
  LPTSTR lpszServer,           // server to execute on
  UINT nLevel,                 // must be 0
  LPBYTE lpBuffer,             // pointer to buffer
  DWORD cBufSize,              // size of buffer
  LPDWORD lpnEntriesRead,      // number of names returned
  LPDWORD lpcbTotalAvailable   // number of bytes available
);

Parameters

lpszServer
Address of the server name on which the DSDM resides.
nLevel
Must be 0.
lpBuffer
Address of a buffer supplied to accept the list of DDE shares. The list of DDE shares is stored as a sequence of null-separated strings terminating with a double null at the end. This parameter can be NULL. If lpBuffer is NULL, the DSDM returns the size of buffer required to hold the list of shares in the lpcbTotalAvailable field.
cBufSize
Specifies the size of the supplied buffer addressed by lpBuffer. Must be 0 if lpBuffer is NULL.
lpnEntriesRead
Address of a variable to receive the total number of shares being enumerated. Must not be NULL.
lpcbTotalAvailable
Address of a variable to receive the total number of bytes needed in the buffer to store the list of DDE shares. Must not be NULL.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions


NDdeShareGetInfo

The NDdeShareGetInfo function is called to retrieve DDE share information from the DSDM. This is usually done for editing.

UINT NDdeShareGetInfo(
  LPTSTR lpszServer,          // server to execute on
  LPTSTR lpszShareName,       // name of share
  UINT nLevel,                // info level must be 2
  LPBYTE lpBuffer,            // contains (NDDESHAREINFO) + data
  DWORD cBufSize,             // size of buffer
  LPDWORD lpnTotalAvailable,  // number of bytes available
  LPWORD lpnItems             // item mask for partial getinfo
);

Parameters

lpszServer
Address of the server name on which the DSDM resides.
lpszShareName
Address of the share name whose information is to be retrieved from the DSDM. This parameter must not be NULL.
nLevel
Must be 2.
lpBuffer
Address of a buffer that is to accept the NDDESHAREINFO structure and associated data pointed to by NDDESHAREINFO pointer fields. This field can be NULL. If lpBuffer is NULL, then the DSDM calculates the number of bytes required to store the requested share information and returns that value in the lpnTotalAvailable field along with the NDDE_BUF_TOO_SMALL error.
cBufSize
Defines the size of the buffer addressed by the lpBuffer field. If lpBuffer is NULL, then cBufSize should be 0.
lpnTotalAvailable
Address of a varaible that receives the count of the total number of bytes needed to store the requested share information. This parameter must not be NULL.
lpnItems
Address of an item selection mask for partial share information retrieval. For Windows NT version 3.1, the item selection mask must be 0.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDDESHAREINFO, NDdeShareSetInfo


NDdeShareSetInfo

The NDdeShareSetInfo function is called to modify DDE share information stored in the NetDDE DSDM. This is usually done after editing.

UINT NDdeShareSetInfo(
  LPTSTR lpszServer,     // server to execute on
  LPTSTR lpszShareName,  // name of share
  UINT nLevel,           // information level must be 2
  LPBYTE lpBuffer,       // address of NDDESHAREINFO
  DWORD cBufSize,        // size of buffer
  WORD sParmNum          // parameter index
);

Parameters

lpszServer
Address of the server name on which the DSDM will be modified.
lpszShareName
Address of the share name whose information is to be modified in the DSDM. This parameter must not be NULL.
nLevel
Must be 2.
lpBuffer
Address of the NDDESHAREINFO structure that defines the new DDE share information to be stored in the DSDM. Currently the DDE share information is modified as a whole, that is, no partial edits are made. This parameter must not be NULL.
cBufSize
Size of the DDE share information addressed by lpBuffer.
sParmNum
Parameter index being modified. The current implementation does not support partial modification and, hence, this value must be 0.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions, NDDESHAREINFO, NDdeShareGetInfo


NDdeTrustedShareEnum

The NDdeTrustedShareEnumfunction lists the names of all network DDE shares that are trusted in the context of the calling process.

UINT NDdeTrustedShareEnum(
  LPTSTR lpszServer,           // server to execute on
  UINT nLevel,                 // must be 0
  LPBYTE lpBuffer,             // pointer to buffer
  DWORD cBufSize,              // size of buffer
  LPDWORD lpnEntriesRead,      // number of names returned
  LPDWORD lpcbTotalAvailable   // number of bytes available
);

Parameters

lpszServer
Address of the server name on which the DSDM resides.
nLevel
Must be 0.
lpBuffer
Address of a buffer supplied to accept the list of trusted DDE shares. The list of trusted DDE shares is returned as a sequence of null-separated strings terminating with a double null at the end. This parameter can be NULL. If the lpBuffer is NULL, the DSDM returns the size of buffer required to hold the list of shares in the lpcbTotalAvailable field.
cBufSize
Specifies the size of the supplied buffer addressed by lpBuffer. This parameter must be 0 if lpBuffer is NULL.
lpnEntriesRead
Address of a variable to receive the total number of trusted shares being enumerated. This parameter must not be NULL.
lpcbTotalAvailable
Address of a variable to receive the total number of bytes needed in the buffer to store the list of trusted DDE shares. This parameter must not be NULL.

Return Values

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.
Import Library: Use nddeapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions


Network DDE Structures

The following structure is used with network DDE.

NDDESHAREINFO

See Also

Network Dynamic Data Exchange Overview, Network DDE Functions


NDDESHAREINFO

The NDDESHAREINFO structure gets and sets DDE share attributes maintained by the NetDDE Share Database Manager (DSDM). The security descriptor associated with each DDE share is not passed through this structure but is accessed through specific functions. The NetDDE DSDM API accepts this structure for set functions; for get functions, the DSDM returns the structure packed into the supplied buffer along with the data referenced by the members lpszShareName, lpszAppTopicList, and lpszItemList.

typedef struct _NDDESHAREINFO {
    LONG   lRevision;
    LPTSTR lpszShareName;
    LONG   lShareType;
    LPTSTR lpszAppTopicList;
    LONG   fSharedFlag;
    LONG   fService;
    LONG   fStartAppFlag;
    LONG   nCmdShow;
    LONG   qModifyId[2];
    LONG   cNumItems;
    LPTSTR lpszItemList;
}NDDESHAREINFO;

Members

lRevision
Specifies the revision level of the NDDESHAREINFO structure. Currently, the revision level is 1.
lpszShareName
Points to a buffer containing a null-terminated string that specifies the name of the share. This string must be no more than MAX_NDDESHARENAME characters long.
lShareType
Specifies the DDE share type(s). A DDE share can assume more than one type. This member can be a combination of the following supported DDE share types:
Share type | Meaning
SHARE_TYPE_OLD | Specifies that the share contains a DDE application/topic pair.
SHARE_TYPE_NEW | Specifies that the share contains an OLE application/topic pair.
SHARE_TYPE_STATIC | Specifies that the share contains a static application/topic pair.

lpszAppTopicList
Points to a buffer containing null-terminated strings for the DDE, OLE, and static application/topic pairs. The buffer should be in the following format:
<DDE application name>|<DDE topic name>\0
        <OLE application name>|<OLE topic name>\0
        <static application name>|<static topic name>\0\0
fSharedFlag
Specifies whether the share is accessible to remote clients for linking. If this flag is set to FALSE, the DDE share will not allow remote users to communicate through it by using DDE. However, local users can still communicate through the DDE share. Local client links are always implied if the associated DACL grants access.
fService
If this flag is set, the DDE share will not check whether the current user has set it as trusted before before allowing DDE communication through it.
fStartAppFlag
If this flag is set and the share is trusted to start applications, NetDDE will attempt to start the application specified by lpszAppTopicList if it cannot initially start a DDE conversation with the application.
nCmdShow
When NetDDE starts an application to initiate a DDE conversation with it, this value is sent to the application by the nCmdShow parameter of the WinMain function. It defines the preferred mode for the application window to be shown in. This parameter is significant only if fStartAppFlag is active. The logged on user in whose context the application is started can also override this option when promoting the share to trusted status. The default for this member is SW_SHOWMAXIMIZED.
qModifyId
An 8-byte serial number that indicates the modification serial number of the DDE share. Every time the DDE share is modified by a NDdeShareSetInfo or NDdeSetShareSecurity call, these values are changed.
cNumItems
Specifies the number of items listed in lpszItemList. If cNumItems is zero, then lpszItemList is empty, and the share information and associated security descriptor apply to all items serviced by the associated application.
lpszItemList
Points to a buffer containing null-terminated strings that specify the items the client application in a DDE transaction can request or start advise loops on. If no items are listed, the DDE share allows any item to be used. The number of items in the list must match the cNumItems count.

QuickInfo

Windows NT: Requires version 3.5 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in nddeapi.h.

See Also

Network Dynamic Data Exchange Overview, Network DDE Structures, NDdeSetShareSecurity, NDdeShareSetInfo, WinMain


Networking (Net)

For OS/2-based servers, the Net functions supported by Microsoft® LAN Manager provided much of the functionality required for a network operating system; this functionality was missing from the local operating system. Windows NT, Windows 95, and Windows 98 have much of this network functionality built in. Therefore, some of the original Net functions are no longer supported.

Windows NT, Windows 95, and Windows 98 support a variety of networking functions. The set of Net functions provide additional capability not covered by other networking functions. In addition, you may use these functions to monitor and administer OS/2-based LAN Manager servers.


About Net Functions

The Net functions supplement the networking functions built into Win32 platforms; they are not the base Win32 networking functions. The Win32 API also provides a network-independent set of network functions (WNet functions) that allow network functions to work across different network vendors' products. If a Win32 function or WNet function exists that could be used by your application, you should convert your code to use the WNet equivalent. There are at least two reasons to make the change:

  1. The WNet functions are network independent, while the Net functions work only on Microsoft networks.
  2. Some of the Win32 functions documented in this SDK may not be supported in future releases Microsoft operating systems if they have been superseded by Win32 functions or WNet functions. Microsoft does not plan to remove specific functions unless equivalent or better functionality is available.

In this documentation, equivalent functions are listed that could be used in place of a Net function. These are the functions your application should use if at all possible.


Net Function Data Types

The following sections discuss the buffers, data alignment, structures, and handles used by the Net functions.


API Buffers

The RPC run time allocates the buffers required to access the Net functions.

  • For a set type function (data sent to the server) the function caller specifies a buffer containing the information structure relevant to the function level but does not specify the buffer length.
  • For a get type function (data returned from the server) the caller does not preallocate a buffer for the return information. The caller passes a LPBYTE * to the function on input. On successful return the buffer pointer will contain a pointer to a buffer containing the return information. When the caller has finished processing the returned information the NetApiBufferFree function must be called. This simplifies the calling code, because the caller does not need to guess at the size of the buffer required and will not need to resize and reissue the function.


API Data Alignment

All structures specified for the Net functions must be 32-bit word aligned. The base size for a structure element is a DWORD.


Enumeration Buffer Lengths

Enumeration functions take an advisory maximum data-length parameter, prefmaxlen, which allows a control on the number of bytes returned from an enumeration call. The preferred length is specified in units of 8-bit bytes. The actual function may return more than the preferred maximum length.

An enumeration call will not return partial entries.


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 a GetInfo call 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, interoperabilty, 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. For example, the enumeration should be restarted from the beginning.


Function Status

The Net functions return zero on success; a nonzero return code indicates an error. Because the Net functions use RPC, the error definitions include RPC error codes. For more information, see Net Errors.


NLS Support

Windows NT: The Net 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.

Windows 95 and Windows 98: Because the system does not support Unicode, the Net functions require ANSI strings.


Parameter Error Reporting

The Add and SetInfo functions return an index for a parameter 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. For functions that are accessed through LAN Manager 2.x servers, this field is returned as PARM_ERROR_UNKNOWN.


RPC Buffer Allocation Errors

Because the RPC run-time 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 32-bit Windows systems.


Net Function Groups

Net functions use the standard-call calling convention and return a DWORD status value. The following modifiers are used in the function declarations:

#define NET_API_STATUS   DWORD
#define NET_API_FUNCTION __stdcall

The Net functions can be divided into the following groups:

  • Access functions
  • Alert functions
  • ApiBuffer functions
  • Audit functions
  • Configuration functions
  • Directory Service (Ds) functions
  • Distributed File System (Dfs) functions
  • Error Logging functions
  • File functions
  • Group functions
  • Local Group functions
  • Message functions
  • Remote Utility functions
  • Replicator functions
  • Schedule functions
  • Server functions
  • Service functions
  • Session functions
  • Share functions
  • Statistics functions
  • Use functions
  • User functions
  • Workstation and workstation user functions


Access Functions

The access functions are obsolete on Windows NT. They work only when the function is accessed with a LAN Manager 2.x system. The Win32 API contains a full set of access control functions for access control. These should be used in place of the Net access functions.


Alert Functions

The alert functions notify network service programs and applications of network events. An event is a particular instance of a process or state of hardware as defined by an application. The alert functions allow applications to indicate when predefined events occur.

Other programs, network services, or internal network components use the NetAlertRaise function to raise an alert, notifying various applications or users when a particular type of event occurs. The Alert category functions, datatypes, structures, and constants are defined in the LMCONS.H, LMERR.H, and LMALERT.H header files. A source program can gain access to these definitions by defining the constants INCL_NETERRORS and INCL_NETALERT, and by including the header file LM.H.

The LMALERT.H include file defines the following classes of events for which alerts are sent out:

  • A network event requiring administrative assistance
  • An entry is added to an error log file
  • A user or application receives a broadcast message
  • A print job completes
  • A user accesses or uses certain applications or resources

You can define other classes of alerts for network applications as needed. For example, an application on a server routinely writes large amounts of data to a disk drive, running the risk of filling the disk. In this case, you might want the event ``no free disk space'' to trigger an alert that notifies the application to pause or terminate the process that is filling the disk.

An application or network service program, also known as a client, registers a request to be notified of an event (or class of events) by calling the NetAlertStart function. You can register the client for several types of events by calling the NetAlertStart function multiple times. Each registration adds an entry to an alert table. An application or network service program receives alert messages through the use of a mailslot (registered as \mailslot\name). If a program requires detailed information about an event, register it as a mailslot.

You can register an application or network service program for one type of event, or for several types, by calling the NetAlertStart function multiple times. For a registered application or network service program, use the NetAlertStop function to remove that application or network service program entry from the alert table for the particular class of event.

The alert functions are:

NetAlertRaise
NetAlertRaiseEx

The NetAlertRaise function is used to indicate that an event has occurred.

The fixed-length header contains the standard alert structure, STD_ALERT.

Additional information is included in the following structures:


ApiBuffer Functions

For remotable functions that return information to the caller, the RPC run time allocates the buffer containing the return information. The ApiBuffer functions are used to manipulate the buffer. The buffer manipulation functions are:

NetApiBufferAllocate
NetApiBufferFree
NetApiBufferReallocate
NetApiBufferSize

When the caller has finished processing the returned information, it must call the NetApiBufferFree function to free the allocated buffer.


Audit Functions

The auditing functions are obsolete on Windows NT. Windows NT uses an integrated event logging mechanism for reporting both audits and errors. The NetAudit and NetErrorLog functions are provided to access LAN Manager 2.x logs. They will report ERROR_NOT_SUPPORTED if called on a Windows NT system.

The auditing functions are:

NetAuditClear
NetAuditRead

Auditing functions control the audit log on a LAN Manager computer. Auditing functions monitor operations on the specified server. If auditing is enabled, each monitored operation generates an audit entry. For example, when a user establishes a connection to the server, a single audit entry is generated.

Audit entries are stored in a binary file called an audit trail or audit log. All Auditing functions perform their operations on this file. LAN Manager defines many types of audit entries.

NetAuditRead reads the audit log. NetAuditClear clears the audit log.

Data Structures

All audit entries include a fixed-length header used in conjunction with variable-length data specific to the entry type. Because of the variable lengths and structures of the ae_data element of the audit entry (it is possible for ae_data to be zero bytes), only the fixed header is defined in the AUDIT_ENTRY structure.

The variable-length portion of the audit entry can contain an offset to a variable-length Unicode string. The offset values are DWORDs. To determine the value of the pointer to this string, add the offset value to the address of ae_data.

The following example illustrates this procedure. Assume that pAE points to a buffer that contains a complete audit entry and that the ae_type member of the AUDIT_ENTRY structure contains the value AE_CONNSTOP, which specifies the predefined AE_CONNSTOP structure. To point the variable pszComputerName to the Unicode string that contains the name of the client whose connection was stopped, an application would perform the following algorithm:

PAUDIT_ENTRY  pAE;             // Fixed part of audit entry
LPAE_CONNSTOP pAEvar;          // Variable-length structure
LPWSTR        pszComputerName; // Pointer to var-length string

// Calculate the offset to the variable-length structure.
pAEvar = (_LPAE_CONNSTOP) (((LPBYTE) pAE) + pAE->ae_data_offset);

// Calculate the offset to the computername.
pszComputerName = ((LPBYTE) pAEvar) + pAEvar->ae_cp_compname;

The following structures are specific to the audit entry type The structures follow the AUDIT_ENTRY header, but they are not necessarily contiguous.


Configuration Functions

The configuration functions are obsolete on Windows NT. They are only for LAN Manager 2.x support. Use the registry functions to retrieve configuration information for Windows NT computers.

Configuration functions retrieve network configuration information. The functions in the Configuration category retrieve information from the LANMAN.INI file. This is an ASCII file that contains configuration information for LAN Manager services as well as network configuration information for user-defined services and applications. It consists of component lines, entry lines, and comment lines, in the following format.

  • Component lines mark the start of a group of information, in this form: [component name]
  • Entry (or parameter) lines contain a parameter and a value:
    entry=value

The entry value can consist of any text. Configuration functions do not process the text, although they do remove leading and trailing spaces. Interpretation of the values is left to the caller. If an entry appears several times in a single component, the NetConfigGetAll function returns each instance; the NetConfigGet function returns only the first instance. Using the same entry name in different components does not affect the data returned by NetConfigGet. The configuration functions are:

NetConfigGet
NetConfigGetAll
NetConfigSet

Configuration functions support the following information level:

CONFIG_INFO_0


Directory Service (Ds) Functions

The Directory Service (DS) functions provide a mechanism for locating a domain controller (DC) in a Windows NT domain. The architecture interacts with clients as well as servers in all versions of Windows NT.The following functions allow developers to work with the domain controller in the directory service:

Function | Description
DsGetDcName | Returns the name of a domain controller (DC) in a specified domain. The DsGetDcName function provides information from the DOMAIN_CONTROLLER_INFO structure.
DsGetSiteName | Returns the name of the site for either the domain controller, member workstation, or the member server.
DsValidateSubnetName | Validates a subnet name of a valid IP address.

The DC locator (DsGetDcName) is implemented by the Netlogon service. Each DC registers its DNS name on the DNS server and its Netbios name using a transport-specific mechanism (for example, in WINS). The DC locator looks up the name, then sends a datagram to (or "pings") the DC that registered the name. For Netbios domain names, the datagram is a mailslot message. For DNS domain names, the datagram is an LDAP UDP search. Each such DC responds indicating that it is currently operational. The first DC to respond is returned to the caller.

The returned DC is cached so that subsequent callers need not repeat the precedingalgorithm, and to encourage all callers to use that same DC. This ensures that a single client has a consistent view of the contents of the DC.

When searching for a DC by DNS domain name, the DC locator will attempt to find a DC in the "closest" site. Each DC registers additional DNS records indicating what site that the DC is in and what sites the DC includes. The DC locator first searches for this site-specific DNS record before searching for the DNS record that is not site-specific (thus preferring a DC in that site). When the DC locator sends a datagram to the DC, the DC looks up the IP address of the client in the Configuration/Sites/Subnet container of the DS to find a subnet object. The SiteObject property of the subnet object defines the name of the site that contains the client. The DC responds to the ping with the name of the site that contains the client, along with an indicator of whether this DC covers that site. If the DC does not include that site and the DC locator has not yet attempted to find a DC in that site, the DC locator tries again to find a DC in the site.

To find the name of the site containing the client,use the DsGetSiteName function. The names of the objects in the Configuration/Sites/Subnet container must be valid subnet names. The DsValidateSubnetName function indicates whether a specified subnet name is valid.


Distributed File System (Dfs) Functions

The Distributed File System (Dfs) functions provide the ability to logically group shares on multiple servers and to transparently link shares into a single hierarchical name space.

Dfs organizes shared resources on a network in a tree structure. Each Dfs tree must have one root volume, a directory hosted by a server running Windows NT Server 4.0 and later. The root volume can have one level of shares, called leaf volumes, beneath it. Each leaf volume in a Dfs tree can be physically located on a different server.

When you add a leaf volume, Dfs creates a blank directory in the root volume directory that is called a junction point to the leaf volume. A junction point is a directory on a Net (formerly LAN Manager) share that points to, or references, a different Net share. When you remove a share that is the last share associated with a junction point, Dfs also deletes the blank directory in the root volume directory.

A Dfs junction point that has one or more shares for its storage has alternate paths. When a junction point includes alternate paths, Dfs distributes requests for storage access among the alternate paths. However, the Dfs software does not replicate information among servers. For this reason it is advisable to use alternate paths for read-only shares. Dfs has a limit of 32 alternate paths for a junction point in a Dfs tree.

An application can use the Dfs functions to:

  • Add a junction point to a Dfs tree.
  • Add an alternate path to a Dfs junction point.
  • Remove a junction point from a Dfs tree.
  • Remove an alternate path from a Dfs junction point.
  • View and configure information about the junction points in a Dfs tree.

The Dfs functions are listed following.

Function | Description
NetDfsAdd | Adds a new junction point or adds a share to an existing junction point.
NetDfsEnum | Enumerates and returns information about all junction points.
NetDfsGetInfo | Returns information about a specific junction point.
NetDfsRemove | Removes a share from a junction point; removes the junction point if the share is the last associated with the specified junction point.
NetDfsSetInfo | Associates information with a junction point.

Dfs functions are available at five information levels:

DFS_INFO_1
DFS_INFO_2
DFS_INFO_3
DFS_INFO_100
DFS_STORAGE_INFO

Shares on computers that are running Windows NT Workstation, Windows 95, Windows 98, or Windows for Workgroups can be published in a Dfs name space. You can also publish any non-Microsoft shares for which client redirectors are available in a Dfs name space. However, unlike a share that is published on a server that is running Windows NT Server 4.0 and later, they cannot host a Dfs share or point to other Dfs shares.


Error Logging Functions

The error logging functions are obsolete on Windows NT. Windows NT uses an integrated event logging mechanism for reporting both audits and errors. The NetAudit and NetErrorLog functions are provided to access LAN Manager 2.x logs. They will report ERROR_NOT_SUPPORTED if called on a Windows NT system.

The error logging functions are:

NetErrorLogClear
NetErrorLogRead

The NetErrorLogRead function reads entries from the error log; and NetErrorLogClear clears the error log and, optionally, saves the entries in a backup file.


Net File Functions

The file functions provide a way to monitor and close the file, device, and pipe resources open on a server. The file functions are:

NetFileClose
NetFileEnum
NetFileGetInfo

Use the NetFileClose function when the file cannot be closed by other means. This function should be used with caution, however, because it does not write to the file the data cached on the client system is obsolete.

The NetFileEnum function returns information about resources open on a server. A file can be opened one or more times by one or more applications. Each file opening is uniquely identified. The NetFileEnum function returns an entry for each file opening. The NetFileGetInfo function returns information about one particular opening of a resource.

File information is available at the following levels.

FILE_INFO_2
FILE_INFO_3

Levels 0 and 1 are not supported. Level 2 returns only the identification number assigned to the resource when it was opened. Level 3 returns the identification number, permissions, file locks, and the name of the user who opened the resource.


Get Functions

The get functions retrieve information about a domain. Use these functions to retrieve information concerning domains, such as local and global user accounts, and workstation and server user accounts. These functions are:

MultinetGetConnectionPerformance
NetGetAnyDCName
NetGetDisplayInformationIndex
NetQueryDisplayInformation

The NetGetDCName function returns the name of the Primary Domain Controller (PDC) for the specified domain, while the NetGetAnyDCName function gets the name of any domain controller for a domain that is directly trusted by the server name. The NetGetDisplayInformationIndex function gets the index of the first display information entry whose name begins with a specified string. The NetQueryDisplayInformation function returns user, computer, or global group account information.

The information returned by NetQueryDisplayInformation is available at the following levels:


Group Functions

The group functions control global groups. A global group contains a number of user accounts from one domain that are grouped together under one group account name. A global group can contain only members from the domain where the global group is created. A global group can contain only user accounts; it cannot contain local groups or other global groups. The group functions are:

NetGroupAdd
NetGroupAddUser
NetGroupDel
NetGroupDelUser
NetGroupEnum
NetGroupGetInfo
NetGroupGetUsers
NetGroupSetInfo
NetGroupSetUsers

To create a group, an application calls NetGroupAdd, supplying a group name. Initially, the group has no members. To assign members to the group, call NetGroupSetUsers. To add a user to an existing global group, call NetGroupAddUser. To set general information about the global group, call NetGroupSetInfo.

The NetGroupDelUser function deletes a specified user name from a group, and NetGroupDel destroys a group. The NetGroupDel function works whether or not the group has any members.

Three group functions retrieve information about the groups on a server: NetGroupEnum produces a list of all groups; NetGroupGetUsers lists all members of a specified group; and NetGroupGetInfo returns general information about the group. Each user account automatically belongs to one of the special global groups Domain Users or None, according to the user's security requirements. Membership of these groups is indirectly controlled by the NetUserAdd, NetUserDel, and NetUserSetInfo functions.

Group account information is available at three levels:

GROUP_INFO_0
GROUP_INFO_1
GROUP_INFO_2

The groups to which a user belongs may be obtained at two information levels.

GROUP_USERS_INFO_0
GROUP_USERS_INFO_1

The following information levels are valid only for NetGroupSetInfo.

GROUP_INFO_1002
GROUP_INFO_1005

For NetGroupSetInfo, parmnum values refer to the members of the GROUP_INFO structure as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of GROUP_INFO structure
GROUP_NAME_PARMNUM | grpi_name
GROUP_COMMENT_PARMNUM | grpi_comment
GROUP_ATTRIBUTES_PARMNUM | grpi_attributes


Handle Functions

The Handle functions allow an application to examine or change the communications parameters for character-device handles and named-pipe handles, provided that the handles refer to devices or pipes opened on a remote server. The Handle functions are:

NetHandleGetInfo
NetHandleSetInfo

The adjustable parameters are based on the LANMAN.INI file entries for chartime, the amount of time the workstation collects data to send to a character device or named pipe, and charcount, the number of characters the workstation stores before it sends data to a character device. See the NET_HANDLE_INFO data structure to obtain the values for chartime and charcount, which determine the workstation data structure elements. In addition, you can use the NetHandleGetInfo function to identify the user of a named pipe, provided the pipe has been opened from a remote server.


Local Group Functions

A local group is a set of users who share common permissions in the security database. A local group can have members that are either users or global groups (global groups can contain only users). The local group functions control members of local groups in a way that can only be used locally on the system on which the local group is defined. On a Windows NT Workstation or a Windows NT non-DC server, you can use only a local group defined on that system. On a Windows NT Domain Controller, a local group defined on the Primary Domain Controller is replicated to all other domain controllers in the domain; as such, you can use such a local group on any domain controller in the domain.The local group functions create or delete local groups, and review or adjust the memberships of local groups. The local group functions are:

NetLocalGroupAdd
NetLocalGroupAddMembers
NetLocalGroupDel
NetLocalGroupDelMember
NetLocalGroupDelMembers
NetLocalGroupEnum
NetLocalGroupGetInfo
NetLocalGroupGetMembers
NetLocalGroupSetInfo
NetLocalGroupSetMembers

A member can be added to a local group by specifying the security identifier (SID) of the member. The LookupAccountName function can be used to translate a member account name to a SID.

To create a local group, an application calls NetLocalGroupAdd , supplying a local group name. Initially, the local group has no members. To assign members to the local group, call NetLocalGroupSetMembers. To add a member to an existing local group, call NetLocalGroupAddMembers. To set general information about the local group, call NetLocalGroupSetInfo.

The NetLocalGroupDelMember function deletes a specified member from a local group, and NetLocalGroupDel disbands a local group, deleting all existing members of the local group first.

Three local group functions retrieve information about the local groups on a server: NetLocalGroupEnum produces a list of all local groups; NetLocalGroupGetMembers lists all members of a specified local group; and NetLocalGroupGetInfo returns general information about the local group.

Group account information is available at three levels:

LOCALGROUP_INFO_0
LOCALGROUP_INFO_1
LOCALGROUP_INFO_1002

Members of a local group can be identified at four information levels:

LOCALGROUP_MEMBERS_INFO_0
LOCALGROUP_MEMBERS_INFO_1
LOCALGROUP_MEMBERS_INFO_2
LOCALGROUP_MEMBERS_INFO_3

The users that belong to a local group can be obtained at one information level:

LOCALGROUP_USERS_INFO_0

For NetLocalGroupSetInfo , parmnum values refer to the members of the LOCALGROUP_INFO structure as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member in group_info structure
LOCALGROUP_NAME_PARMNUM | lgrpi_name
LOCALGROUP_COMMENT_PARMNUM | lgrpi_comment


Message Functions

The message functions send and receive messages and manipulate message aliases. The message functions are:

NetMessageBufferSend
NetMessageNameAdd
NetMessageNameDel
NetMessageNameEnum
NetMessageNameGetInfo

A message is a buffer of text data sent to a user or application on the network. To receive a message, a user or application must register a message alias in a computer's table of message names. This can be done by using NetMessageNameAdd. A message name table contains a list of registered message aliases (users and applications) permitted to receive messages.

The messenger service must be running on the receiving computer, which will display a pop-up message when the message is received. In addition, the Workstation service must be running on the local computer. Netbios is the transport mechanism used between the sender and receiver.

The aliases registered in the message name table are case insensitive. NetMessageNameDel deletes a specific message alias from the message name table. The NetMessageNameEnum function lists all the aliases stored in the message name table. The NetMessageNameGetInfo function retrieves information about a particular message alias in the message name table.

To send a message, an application calls NetMessageBufferSend.

Message functions are available at two information levels:

MSG_INFO_0
MSG_INFO_1

MSG_INFO_1 exists only for compatability. The Windows NT messenger will not forward names or allow names to be forwarded to it.


Remote Utility Function

The remote utility function NetRemoteTOD enables applications to access the time-of-day information on a remote server.

The remote time-of-day information is available at one information level:

TIME_OF_DAY_INFO


Replicator Functions

The Windows NT replicator service maintains identical sets of files and directories on different servers and workstations. When you update files on one server, the replicator service replaces the replicated files on other servers and workstations with the updated files. This replication process not only simplifies the task of updating and coordinating files, but it maintains the integrity of the replicated data.

Replication is controlled by options you set in the LANMAN.INI file using the following categories of replicator functions:

  • Replicator configuration functions
  • Replicator export directory functions
  • Replicator import directory functions

To replicate a set of files and directories on several computers, you place a master set of files and directories on a server that you designate as an export server. You then designate servers and workstations that receive the replicated files as import servers. The export servers keep the set of master files in an export directory tree of up to 32 levels. Each directory may contain as many as 1000 files. The import servers and workstations have corresponding import directories. When you change a file, or add or delete a directory or file in the export directory, the replicator service copies the same changes to the corresponding import directories on all import servers and workstations.

A network can have any number of export and import servers. A server can be both an export and an import server. However, you can configure only workstations as import servers.

If you are unable to replicate files, before using the replicator functions, check the Control Panel Services application to make sure the replicator service is configured to log on using a specific user account. This user account must be a member of the Replicator local group, and it must not be disabled or lacking permission to access the import and export trees on the respective servers. Failure specify the user account is the most common error in configuring the Replicator service.

The Windows NT Replicator service is intended to copy relatively small directory trees. If you are attempting to replicate multimegabyte directory trees or trees containing thousands of directories and files, you should consider some other means of doing so.

The change from the file system based control in LAN Manager 2.x to replicator function control in Windows NT has the following implications:

  • Applications can no longer delete a directory in the import path of a client to stop receiving updates from its master.
  • Applications can no longer use the REPL.INI file in each replicated directory on a master to control the method of replication.
  • Applications can no longer lock or unlock a directory on a master from being replicated by creating or deleting the USERLOCK.* file(s).
  • Applications can no longer lock or unlock a directory on a client from receiving updates from its master by creating or deleting USERLOCK.* files.
  • Applications that depend on the LAN Manager 2.x behavior of ignoring locks for file integrity trees will need to be modified. (Windows NT policy differs from LAN Manager 2.x policy; under Windows NT the locks are always respected.)

Each of the intended operations listed preceding can be specified to the Windows NT replicator service through an appropriate function.

Any user or application logged on as a member of the administration group or the server operator group on a local or remote export server can modify the parameters that control the replication service.

Replicator Configuration Functions

The configuration parameters of the replicator service can be examined and modified using the replicator configuration functions. The replicator configuration functions are:

NetReplGetInfo
NetReplSetInfo

The configuration parameters of the replictor can be examined using NetReplGetInfo. They can be modified using NetReplSetInfo.

The replicator configuration information structures are:

REPL_INFO_0
REPL_INFO_1000
REPL_INFO_1001
REPL_INFO_1002
REPL_INFO_1003

Replicator Export Directory Functions

The replicator export directory functions control top-level directories under the export path on the master. The replicator export directory functions are:

NetReplExportDirAdd
NetReplExportDirDel
NetReplExportDirEnum
NetReplExportDirGetInfo
NetReplExportDirLock
NetReplExportDirSetInfo
NetReplExportDirUnlock

A user can create a new directory under the export path and the Replicator service will automatically replicate that directory. Or, a directory under the export path can be registered using NetReplExportDirAdd. When adding a directory to be replicated using these functions, the replication controls (integrity and extent) are specified using the NetReplExportDirAdd function. If the directory is created in the file system and no replicator functions are called, then the directory is treated as having file integrity and tree extent.

The integrity control determines when a master updates a client. When integrity is REPL_INTEGRITY_FILE, the client gets a replica of a file within the directory when it is not in use (being changed or replicated). When integrity is set to REPL_INTEGRITY_TREE, every file and directory within the replicated directory must be stable for the amount of time specified by the guardtime parameter before the client is updated. The extent control determines whether the entire tree within the directory is replicated (REPL_EXTENT_TREE) or only the files in the first-level directory is replicated (REPL_EXTENT_FILE).

The replication controls of each replicated directory can be examined using NetReplExportDirGetInfo, and dynamically modified using NetReplExportDirSetInfo. These control fields used to be specified in the REPL.INI file within each replicated directory on LAN Manager 2.x, and they could not be dynamically set. On Windows NT, the REPL.INI file is not used and will be ignored in the replication process.

The NetReplExportDirEnum function returns a list of directories that are currently replicated. The NetReplExportDirDel function removes registration from a directory so that it is no longer replicated.

The lock status information is returned in two fields: lockcount and locktime. The lockcount field indicates the number of outstanding locks on a directory. The locktime field indicates the time (in seconds since 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.

The NetReplExportDirLock function locks a directory so that it is not replicated, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplExportDirUnlock . The replication does not resume unless all outstanding locks on that directory are released, and the lock reference count is returned to 0. (The locktime field is automatically set to 0 when lockcount is 0.)

The replicator export directory functions can be called regardless of whether the Replicator service is running. If the Replicator service is running as a master, any modification to the directory controls takes effect immediately, and is persistent after the Replicator service has been stopped. If the Replicator service is not started, the controls for the directory is stored as persistent information and will take effect when the Replicator service starts up.

The replicator export directory functions are available at the following information levels:

REPL_EDIR_INFO_0
REPL_EDIR_INFO_1
REPL_EDIR_INFO_2
REPL_EDIR_INFO_1000
REPL_EDIR_INFO_1001

Replicator Import Directory Functions

The replicator import directory functions designate the top-level directories under the import path to receive updates on. They also return status information about a replicated directory on the client. On LAN Manager 2.x, a user must create a directory under the import path and the Replicator service automatically replicates to it. The replicator import directory functions are:

NetReplImportDirAdd
NetReplImportDirDel
NetReplImportDirEnum
NetReplImportDirGetInfo
NetReplImportDirLock
NetReplImportDirUnlock

On Windows NT, import directories are automatically added if they are exported by an export server from which importer is importing. Another way to register a directory in advance of it being exported, is to use the NetReplImportDirAdd functions. This function does not create the directory itself. This is useful if you wish to modify some of the properties of the import directory (for example, to lock it) prior to it first beginning to import this directory.

The NetReplImportDirDel function unregisters a directory. This is used to clean up a directory that is no longer being exported. It will not stop replication if there is an active exporter, since it will be re-registered the next time the exporter tells the importer what directories it is exporting. If you wish to prevent importing of an actively exported directory, use NetReplImportDirLock.

The NetReplImportDirEnum function lists all the directories that are replicated to a client, and NetReplImportDirGetInfo returns the status of a specified directory.

The status information of a directory consists of the replication state, the UNC computer name of the master (mastername), and the time (in seconds since 1970, GMT) when the directory was last updated (last_update_time). If the state is REPL_STATE_OK, the directory currently has a master, and is receiving regular update notices from it. If the state is REPL_STATE_NO_MASTER, the directory is not supported by any master, and it is typically empty. If the state is REPL_STATE_NO_SYNC, the directory has a master, but the master has not sent any update notices within the interval time period. This may be due to a communication failure, the master crashing, the directory being locked, files in the client directory being opened at update time, or an unstable REPL_INTEGRITY_TREE integrity directory on the master. If the client Replicator service is not started, the state is REPL_STATE_NEVER_REPLICATED, mastername is a NULL string, and last_update_time is 0. The NetReplImportDirLock function locks a directory so that it does not receive updates, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplImportDirUnlock . The directory is not updated unless all outstanding locks on that directory are released, and the lock reference count is returned to 0.

The lock status information is returned in two fields: lockcount and locktime. The lockcount field indicates the number of outstanding locks on a directory. The locktime field indicates the time (in seconds since 1970, GMT) when the directory was first locked. (locktime is set to 0 whenever lockcount goes to 0.)

The replicator import directory functions can be called whether the Replicator service is running or not. If the Replicator service is running as a client, directory adds or deletes take effect immediately, and is persistent after the Replicator service has been stopped. If the Replicator service is not started, any added directory will receive updates when the Replicator service starts up (if there exists a master that exports the directory).

The replicator import directory function are available at the following information levels:


Schedule Functions

The schedule service functions are used to submit and manage jobs to be executed at a specifed computer at a specified time (or times) in the future. Jobs can be commands and programs. Jobs can be managed at remote and local computers, provided schedule service is running at a specified computer. The schedule service functions are:

NetScheduleJobAdd
NetScheduleJobDel
NetScheduleJobEnum
NetScheduleJobGetInfo

Schedule service functions are also known as "Job" and "AT command" functions.

Schedule service functions are job submittal (NetScheduleJobAdd), job cancellation (NetScheduleJobDel), job enumeration (NetScheduleJobEnum) and retrieving information about a particular job (NetScheduleJobGetInfo). In order for these functions to succeed, a caller must have administrator's privilege at a computer where Schedule service is running.

Structures

The AT_INFO structure is used by NetScheduleJobAdd to specify a job to be added, and by NetScheduleJobGetInfo to return information about an already submitted job. The AT_ENUM structure is used by NetScheduleJobEnum to enumerate and return information about an entire queue of already submitted jobs.


Server Functions

The server functions perform administrative tasks on a local or remote server. The server functions are:

  • NetServerDiskEnum retrieves a list of local disk drives on a server.
  • NetServerEnum lists all visible servers of specified types in the specified domain.
  • NetServerGetInfo retrieves information about a specified server.
  • NetServerSetInfo sets the operating parameters for a server.

Any user or application with admin group membership on a local or remote server can perform administrative tasks on that server to control its operation, user access, and resource sharing. The low-level parameters that affect a server's operation can be examined and modified by calling NetServerGetInfo and NetServerSetInfo.

You can examine and modify certain low-level parameters that affect a server's operation, defined in the server's LANMAN.INI file by calling the NetServerGetInfo and NetServerSetInfo functions. The NetServerEnum function lists all visible servers of specified types in the specified domains. Most server category functions execute only on a remote server. The NetServerEnum function can execute on either a local workstation or remote server, but all other server category functions executed on a local workstation return NERR_RemoteOnly.

The server-specific information is available at the following levels, starting at base level 100:

SERVER_INFO_100
SERVER_INFO_101
SERVER_INFO_102
SERVER_INFO_402
SERVER_INFO_403
SERVER_INFO_502
SERVER_INFO_503
SERVER_INFO_1501
SERVER_INFO_1502
SERVER_INFO_1503
SERVER_INFO_1506
SERVER_INFO_1509
SERVER_INFO_1510
SERVER_INFO_1511
SERVER_INFO_1512
SERVER_INFO_1513
SERVER_INFO_1515
SERVER_INFO_1516
SERVER_INFO_1518
SERVER_INFO_1523
SERVER_INFO_1528
SERVER_INFO_1529
SERVER_INFO_1530
SERVER_INFO_1533
SERVER_INFO_1534
SERVER_INFO_1535
SERVER_INFO_1536
SERVER_INFO_1538
SERVER_INFO_1539
SERVER_INFO_1540
SERVER_INFO_1541
SERVER_INFO_1542
SERVER_INFO_1544
SERVER_INFO_1550
SERVER_INFO_1552

The server information levels available in LAN Manager 2.x are no longer available in the Net functions. However, the following structures are supported on LAN Manager 2.x systems:

SERVER_INFO_1005
SERVER_INFO_1010
SERVER_INFO_1016
SERVER_INFO_1017
SERVER_INFO_1018
SERVER_INFO_1107

For NetServerSetInfo, parmnum values refer to the members of the SERVER_INFO structures as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of SERVER_INFO structure
SV_NAME_PARMNUM | sv_name
SV_VERSION_MAJOR_PARMNUM | sv_version_major
SV_VERSION_MINOR_PARMNUM | sv_version_minor
SV_TYPE_PARMNUM | sv_type
SV_COMMENT_PARMNUM | sv_comment
SV_USERS_PARMNUM | sv_users
SV_DISC_PARMNUM | sv_disc
SV_HIDDEN_PARMNUM | sv_hidden
SV_ANNOUNCE_PARMNUM | sv_announce
SV_ANNDELTA_PARMNUM | sv_anndelta
SV_USERPATH_PARMNUM | sv_userpath
SV_ULIST_MTIME_PARMNUM | sv_ulist_mtime
SV_GLIST_MTIME_PARMNUM | sv_glist_mtime
SV_ALIST_MTIME_PARMNUM | sv_alist_mtime
SV_ALERTS_PARMNUM | sv_alerts
SV_SECURITY_PARMNUM | sv_security
SV_NUMADMIN_PARMNUM | sv_numadmin
SV_LANMASK_PARMNUM | sv_lanmask
SV_GUESTACC_PARMNUM | sv_guestacc
SV_CHDEVS_PARMNUM | sv_chdevs
SV_CHDEVQ_PARMNUM | sv_chdevq
SV_CHDEVJOBS_PARMNUM | sv_chdevjobs
SV_CONNECTIONS_PARMNUM | sv_connections
SV_SHARES_PARMNUM | sv_shares
SV_OPENFILES_PARMNUM | sv_openfiles
SV_SESSOPENS_PARMNUM | sv_sessopens
SV_SESSVCS_PARMNUM | sv_sessvcs
SV_SESSREQS_PARMNUM | sv_sessreqs
SV_OPENSEARCH_PARMNUM | sv_opensearch
SV_ACTIVELOCKS_PARMNUM | sv_activelocks
SV_NUMREQBUF_PARMNUM | sv_numreqbuf
SV_SIZREQBUF_PARMNUM | sv_sizreqbuf
SV_NUMBIGBUF_PARMNUM | sv_numbigbuf
SV_NUMFILETASKS_PARMNUM | sv_numfiletasks
SV_ALERTSCHED_PARMNUM | sv_alertsched
SV_ERRORALERT_PARMNUM | sv_erroralert
SV_LOGONALERT_PARMNUM | sv_logonalert
SV_ACCESSALERT_PARMNUM | sv_accessalert
SV_DISKALERT_PARMNUM | sv_diskalert
SV_NETIOALERT_PARMNUM | sv_netioalert
SV_MAXAUDITSZ_PARMNUM | sv_maxauditsz
SV_SRVHEURISTICS_PARMNUM | sv_srvheuristics
SV_AUDITEDEVENTS_PARMNUM | sv_auditedevents
SV_AUTOPROFILE_PARMNUM | sv_autoprofile
SV_MAXWORKITEMS_PARMNUM | sv_maxworkitems
SV_RAWWORKITEMS_PARMNUM | sv_rawworkitems
SV_IRPSTACKSIZE_PARMNUM | sv_irpstacksize
SV_SESSUSERS_PARMNUM | sv_sessusers
SV_SESSCONNS_PARMNUM | sv_sessconns
SV_MAXNONPAGEDMEMORYUSAGE_PARMNUM | sv_maxnonpagedmemoryusage
SV_MAXPAGEDMEMORYUSAGE_PARMNUM | sv_maxpagedmmeoryusage
SV_ENABLEOFTCOMPAT_PARMNUM | sv_enablesoftcompat


Server Transport Functions

The server transport functions handle binding and unbinding of transports to and from the server and redirector, and also enumerate the transports used by a component. The server transport functions are:

NetServerTransportAdd
NetServerTransportDel
NetServerTransportEnum

The server transport functions deal with transports managed by the server, and the workstation transport functions deal with transports managed by the redirector. The NetServerTransportAdd function allows the user to bind the transport to the server. The NetServerTransportDel function allows the user to unbind the server from the transport.

The NetServerTransportAdd and NetServerTransportDel functions respectively bind or unbind the transport to the server. File sharing between the transport device and the server has two components: the server running on the computer that has the files, and an SMB client that accesses the files. The client computer communicates to the server computer over a local area network using a transport protocol (like TCP, NetBEUI , XNS.) and sends requests to the server computer to retrieve bits and pieces of files. The piece of software on the client computer generating the file requests is called the redirector because it is redirecting local file requests to the server computer. The piece of software on the server computer receiving and acting on these file requests is called the server because it is serving the clients. The format specific to these requests is called the Server Message Block (SMB) protocol.

The NetServerTransportEnum function enumerates the transports that are managed by the server.

The NetWkstaTransport functions perform equivalent operations for the workstation. The workstation transport function are:

NetWkstaTransportAdd
NetWkstaTransportDel
NetWkstaTransportEnum

Server transport functions are available at one information level: SERVER_TRANSPORT_INFO_0

Workstation transport functions are available at one information level: WKSTA_TRANSPORT_INFO_0


Service Functions

A complete set of service functions are provided in the Win32 API. These should be used in place of the NetService functions, unless you need to control services on a LAN Manager 2.x server.

The service functions control services. A service is an application that an administrator can control using the Service Controller interfaces. The service functions are:

NetServiceControl
NetServiceEnum
NetServiceGetInfo
NetServiceInstall

Services allow administrators to control applications on the network and maintain the integrity of users' data. On a typical network, applications are shared by many users. If an administrator terminates an application running on a server, a user who has not finished working with that application can lose important data. When an application is implemented as a service, the service controller checks the status before changing the state of the service. Windows NT Networking provides several standard services, such as the Workstation, Server, and Messenger services.

A service can be started using the service functions. At startup time, the service defines whether it can be stopped, paused, and continued.

The NetServiceControl function controls the operations of network services, and it can provide time hints to controlling applications. The NetServiceEnum function retrieves information about all started services. The NetServiceGetInfo function retrieves information about a particular started service. The NetServiceInstall function starts a network service.

The service functions provide service information at three levels:


Session Functions

The session functions control network sessions established between workstations and servers. They require that the Server service be started on the specified server. The session functions are:

NetSessionDel
NetSessionEnum
NetSessionGetInfo

A session is a link between a workstation and a server. It is established the first time a workstation makes a connection with a shared resource on the server. Until the session ends, all further connections between the workstation and the server are part of this same session. To end a session, an application on the server end of a connection calls NetSessionDel . This deletes all current connections between the workstation and the server. The NetSessionEnum function returns information about all sessions established for a server. The NetSessionGetInfo function returns information about a particular session.

Per-user information is managed by the NetSession functions through the use of the username parameter. Since there can be multiple users per session, this parameter is necessary to access the user-specific information for the session.

Session functions are available at five information levels:

SESSION_INFO_0
SESSION_INFO_1
SESSION_INFO_2
SESSION_INFO_10
SESSION_INFO_502

Note that sesi_username cannot be NULL and sesi1_flags and sesi2_flags can take the following bits:

SESS_GUEST

0x00000001

SESS_NONENCRYPTION

0x00000002


Share Functions

The 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:

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.

The WNetEnumResource function should be used instead of the NetShareEnum function, which is obsolete.

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 may also specify a Security Descriptor to be associated with a share, which specifies which users will be allowed to access files through this share, and with what type of access.

Net functions define three types of 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.

Share functions are available at four information levels:

SHARE_INFO_0
SHARE_INFO_1
SHARE_INFO_2
SHARE_INFO_502

The following information levels are valid only for NetShareSetInfo:

SHARE_INFO_1004
SHARE_INFO_1006

The following is supported only on Windows NT:

SHARE_INFO_1501

For NetShareSetInfo , parmnum values refer to the members of the SHARE_INFO structure, as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of SHARE_INFO structure
SHARE_NETNAME_PARMNUM | shi_netname
SHARE_TYPE_PARMNUM | shi_type
SHARE_REMARK_PARMNUM | shi_remark
SHARE_PERMISSIONS_PARMNUM | shi_permissions
SHARE_MAX_USES_PARMNUM | shi_max_uses
SHARE_CURRENT_USES_PARMNUM | shi_current_uses
SHARE_PATH_PARMNUM | shi_path
SHARE_PASSWD_PARMNUM | shi_passwd
SHARE_FILE_SD_PARMNUM | shi_security_descriptor


Statistics Functions

Windows NT accumulates a set of operating statistics for workstations and servers from the time that the Workstation or Server service is started. The NetStatisticsGet2 is called to get those statistics. Because Windows NT and LAN Manager 2.x workstations collect a different set of statistics, the caller must know whether the server is Windows NT or LAN Manager 2.x (which can be discovered using the NetServerGetInfo function) and interpret the returned buffer accordingly.

NetStatisticsGet2 returns a STAT_WORKSTATION_0 structure when workstation statistics are requested; it returns a STAT_SERVER_0 structure when server statistics are requested.


Use Functions

The WNetAddConnection2, WNetCancelConnection2 WNetEnumResource, WNetGetConnection functions should be used instead of the NetUse functions, which are obsolete.

The use functions examine or control connections (uses) between workstations and servers. They are:

NetUseAdd
NetUseDel
NetUseEnum
NetUseGetInfo

Connections are distinguished from sessions: a session is established the first time a workstation makes a connection to a shared resource on the server; all further connections between the workstation and the server are part of this same session until the session ends. Two types of connections can be made: device-name connections (which can only be explicit) and universal-naming convention (UNC) connections (which can be explicit or implicit).

Connections are made on a per-user basis. A connection made by a user is deleted when that user logs off. For this reason the NetUse functions are local only, since a connection set up by a remote user would not be accessible to any other users, even the user that was interactively logged onto that computer.

The NetUseAdd function creates a device-name connection or an explicit UNC connection. Implicit UNC connections are made by the function responsible for the connection.

The NetUseAdd function establishes an explicit connection between the local computer and a resource shared on a server by redirecting a local device name to the share name of a remote server resource (\\<servername>\<sharename>). Once a device-name connection is made, users or applications can use the remote resource by specifying the local device name. To establish an implicit UNC connection, an application passes the share name of a resource to any function that accepts UNC paths. The function accepts the UNC name and makes a connection to the specified share name. All further requests on this connection require the full share name.

The NetUseDel function ends a connection to a shared resource. The NetUseEnum function enumerates all current connections between the local computer and resources on remote servers. The NetUseGetInfo function returns information about a connection to a shared resource.

The use functions are available at three information levels:

USE_INFO_0
USE_INFO_1

Information level 2 is not available if the function is accessed with a LAN Manager 2.x system. In that case, ERROR_NOT_SUPPORTED will be returned.

USE_INFO_2


User Functions

The user functions control a user's account in the security database. The user functions are:

NetUserAdd
NetUserChangePassword
NetUserDel
NetUserEnum
NetUserGetGroups
NetUserGetInfo
NetUserGetLocalGroups
NetUserSetGroups
NetUserSetInfo

Each user or application that accesses resources must have an account in the security database. The Windows NT server directory services use this user account to verify that the user or application has permission to use a resource. When a user or an application requests access to a resource, the security system checks for an appropriate user account or group account to permit the access.

The NetUserEnum can be used to list all user accounts in a domain. An application can verify the groups to which a user belongs by calling NetUserGetGroups, which returns a list of global group names. The NetUserGetLocalGroups function does the same for local groups. When a user account is no longer needed, use NetUserDel to delete the account from the server. Once the account is removed, the user can no longer access the server, except by using the guest account. Because the user's password is confidential, it is not returned by NetUserEnum or NetUserGetInfo . The password is initially assigned when NetUserAdd is called. NetUserChangePassword function changes a user's password for a specified network server or domain. The NetUserSetInfo function sets the password and other elements of a user account.

User account information is available at seven levels:

USER_INFO_0
USER_INFO_1
USER_INFO_2
USER_INFO_3
USER_INFO_10
USER_INFO_11
USER_INFO_20

The following information levels are valid only for NetUserSetInfo:

USER_INFO_1003
USER_INFO_1005
USER_INFO_1006
USER_INFO_1007
USER_INFO_1008
USER_INFO_1009
USER_INFO_1010
USER_INFO_1011
USER_INFO_1012
USER_INFO_1013
USER_INFO_1014
USER_INFO_1017
USER_INFO_1018
USER_INFO_1020
USER_INFO_1023
USER_INFO_1024
USER_INFO_1025
USER_INFO_1051
USER_INFO_1052
USER_INFO_1053

For NetUserSetInfo, parmnum values refer to the members of the USER_INFO structure, as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of user_info structure
USER_NAME_PARMNUM | usri_name
USER_PASSWORD_PARMNUM | usri_password
USER_PASSWORD_AGE_PARMNUM | usri_password_age
USER_PRIV_PARMNUM | usri_priv
USER_HOME_DIR_PARMNUM | usri_home_dir
USER_COMMENT_PARMNUM | usri_comment
USER_FLAGS_PARMNUM | usri_flags
USER_SCRIPT_PATH_PARMNUM | usri_script_path
USER_AUTH_FLAGS_PARMNUM | usri_auth_flags
USER_FULL_NAME_PARMNUM | usri_full_name
USER_USR_COMMENT_PARMNUM | usri_usr_comment
USER_PARMS_PARMNUM | usri_parms
USER_WORKSTATIONS_PARMNUM | usri_workstations
USER_LAST_LOGON_PARMNUM | usri_last_logon
USER_LAST_LOGOFF_PARMNUM | usri_last_logoff
USER_ACCT_EXPIRES_PARMNUM | usri_acct_expires
USER_MAX_STORAGE_PARMNUM | usri_max_storage
USER_UNITS_PER_WEEK_PARMNUM | usri_units_per_week
USER_LOGON_HOURS_PARMNUM | usri_logon_hours
USER_PAD_PW_COUNT_PARMNUM | usri_bad_pw_count
USER_NUM_LOGONS_PARMNUM | usri_num_logons
USER_LOGON_SERVER_PARMNUM | usri_logon_server
USER_COUNTRY_CODE_PARMNUM | usri_country_code
USER_CODE_PAGE_PARMNUM | usri_code_page
USER_PRIMARY_GROUP_PARMNUM | usri_primary_group_id
USER_PROFILE | usri_profile
USER_HOME_DIR_DRIVE_PARMNUM | usri_home_dir_drive


User Modal Functions

The user modal functions control the system-wide parameters that affect the Windows NT Security system behavior. The user modal functions are:

NetUserModalsGet
NetUserModalsSet

The NetUserModalsGet and NetUserModalsSet functions examine and modify the modal settings, which are global parameters that affect every account in the database (for example, the minimum allowable password length). All modal settings can be altered by calling NetUserModalsSet . Most of the modals can also be altered by using the net accounts command. The NetUserModalsGet and NetUserModalsSet functions do not require the server to have user-level security.

User modal information is available at four levels:

USER_MODALS_INFO_0
USER_MODALS_INFO_1
USER_MODALS_INFO_2
USER_MODALS_INFO_3

The following information levels are valid only for NetUserModalsSet and replace the older way of passing in a Parmnum to set a specific field:

USER_MODALS_INFO_1001
USER_MODALS_INFO_1002
USER_MODALS_INFO_1003
USER_MODALS_INFO_1004
USER_MODALS_INFO_1005
USER_MODALS_INFO_1006
USER_MODALS_INFO_1007

For NetUserModalsSet , parmnum values refer to the members of the MODALS_INFO structure, as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of modals_info structure
MODALS_MIN_PASSWD_LEN_PARMNUM | usrmod_min_passwd_len
MODALS_MAX_PASSWD_AGE_PARMNUM | usrmod_max_passwd_age
MODALS_MIN_PASSWD_AGE_PARMNUM | usrmod_min_passwd_age
MODALS_FORCE_LOGOFF_PARMNUM | usrmod_force_logoff
MODALS_PASSWD_HIST_LIST_PARMNUM | usrmod_passwd_hist_list
MODALS_ROLE_PARMNUM | usrmod_role
MODALS_PRIMARY_PARMNUM | usrmod_primary
MODALS_DOMAIN_NAME_PARMNUM | usrmod_domain_name
MODALS_DOMAIN_ID_PARMNUM | usrmod_domain_id


Workstation and Workstation User Functions

The workstation functions perform administrative tasks on a local or remote workstation. Any user or application with admin group membership on a local or remote server can perform administrative tasks on that workstation to control its operation, user access, and resource sharing. The workstation functions are:

NetWkstaGetInfo
NetWkstaSetInfo

The workstation user functions allow access to user-specific information. The user-specific information is separated from the workstation information because there can be more than one user on a workstation. The workstation user functions are:

NetWkstaUserEnum
NetWkstaUserGetInfo
NetWkstaUserSetInfo

The low-level parameters that affect a workstation's operation can be examined and modified by calling NetWkstaGetInfo and NetWkstaSetInfo.

The workstation API structures are restructured from those of LAN Man 2.x to allow the information to be grouped by type and security accesses. The LAN Manager 2.x workstation information format is discontinued due to the following problems:

  • The base level (0 and 1) were not grouped by accessibility such that a non superset level (level 10) was required to allow guest access to the information.
  • Platform specific implementation information was included in the base levels such that every platform had to return all information including a default for non-relevant fields. This grew the size of the information structures unneccessarily, making the function cumbersome to use.

The workstation functions allow access to two discrete groups of workstation information:

  • System information.
  • Platform specific information (Windows NT, OS/2, MS-DOS, and so on)

Within each group the fields are categorized by security access such that the guest accessible fields are a subset of the user accessible fields that are a subset of the admin accessible fields.

The system information structure contains a platform base number that identifies the levels and format of the platform-specific information structures.

The workstation function information structures are as follows:

WKSTA_INFO_100
WKSTA_INFO_101
WKSTA_INFO_102
WKSTA_INFO_302
WKSTA_INFO_402

The workstation user function information structures are:

WKSTA_USER_INFO_0
WKSTA_USER_INFO_1
WKSTA_USER_INFO_1101

For NetWkstaSetInfo, parmnum values refer to the members of the workstation data information structure, as follows. These values are used when indicating an error in a specific parameter through parm_err.

parmnum value | Member of wksta_info structure
WKSTA_PLATFORM_ID_PARMNUM | wki_platform_id
WKSTA_COMPUTERNAME_PARMNUM | wki_computername
WKSTA_LANGROUP_PARMNUM | wki_langroup
WKSTA_OTH_DOMAINS_PARMNUM | wki_oth_domains
WKSTA_VER_MAJOR_PARMNUM | wki_ver_major
WKSTA_VER_MINOR_PARMNUM | wki_ver_minor
WKSTA_LOGGED_ON_USERS_PARMNUM | wki_logged_on_users
WKSTA_LANROOT_PARMNUM | wki_lanroot
WKSTA_LOGON_DOMAIN_PARMNUM | wki_logon_domain
WKSTA_LOGON_SERVER_PARMNUM | wki_logon_server
WKSTA_CHARWAIT_PARMNUM | wki_char_wait
WKSTA_CHARTIME_PARMNUM | wki_collection_time
WKSTA_CHARCOUNT_PARMNUM | wki_maximum_collection_count
WKSTA_KEEPCONN_PARMNUM | wki_keep_conn
WKSTA_KEEPSEARCH_PARMNUM | wki_keep_search
WKSTA_MAXCMDS_PARMNUM | wki_max_cmds
WKSTA_NUMWORKBUF_PARMNUM | wki_num_work_buf
WKSTA_MAXWRKCACHE_PARMNUM | wki_max_wrk_cache
WKSTA_SESSTIMEOUT_PARMNUM | wki_sess_timeout
WKSTA_SIZERROR_PARMNUM | wki_siz_error
WKSTA_NUMALERTS_PRAMNUM | wki_num_alerts
WKSTA_NUMSERVICES_PARMNUM | wki_num_services
WKSTA_ERRLOGSZ_PARMNUM | wki_errlog_sz
WKSTA_PRINTBUFTIME_PARMNUM | wki_print_buf_time
WKSTA_NUMCHARBUF_PARMNUM | wki_num_char_buf
WKSTA_SIZCHARBUF_PARMNUM | wki_siz_char_buf
WKSTA_WRKHEURISTICS_PARMNUM | wki_wrk_heuristics
WKSTA_MAILSLOTS_PRAMNUM | wki_mailslots
WKSTA_MAXTHREADS_PARMNUM | wki_max_threads
WKSTA_SIZWORKBUF_PARMNUM | wki_siz_work_buf
WKSTA_DORMANTTIMEOUT_PARMNUM | wki_dormant_timeout
WKSTA_LOCKQUOTA_PARMNUM | wki_lock_quota
WKSTA_LOCKINCREMENT_PARMNUM | wki_lock_increment
WKSTA_LOCKMAXIMUM_PARMNUM | wki_lock_maximum
WKSTA_PIPEINCREMENT_PRAMNUM | wki_pipe_increment
WKSTA_PIPEMAXIMUM_PARMNUM | wki_pipe_maximum
WKSTA_RAWREADTHRESHOLD_PARMNUM | wki_raw_read_threshold
WKSTA_USEOPLOCKING_PARMNUM | wki_use_opportunistic_locking
WKSTA_USEOPBATCH_PARMNUM | wki_use_op_batch
WKSTA_USEUNLOCKBEHIND_PARMNUM | wki_use_unlock_behind
WKSTA_USECLOSEBEHIND_PARMNUM | wki_use_close_behind
WKSTA_BUFNAMEDPIPES_PARMNUM | wksta_buf_named_pipes
WKSTA_USELOCKANDREADANDUNLOCK _PARMNUM | wki_use_lock_and_read_and _unlock
WKSTA_UTILIZENTCACHING_PARMNUM | wki_utilize_nt_caching
WKSTA_USERAWREAD_PARMNUM | wki_use_raw_read
WKSTA_USEWRITERAWWITHDATA_PARMNUM | wki_use_write_raw_with_data
WKSTA_USEENCRYPTION_PARMNUM | wki_use_encryption
WKSTA_BUFFILESWITHDENYWRITE _PARMNUM | wki_buf_files_with_deny_write
WKSTA_BUFREADONLYFILES_PRAMNUM | wki_buf_read_only_files
WKSTA_FORCECORECREATEMODE_PARMNUM | wki_force_core_create_mode
WKSTA_USE512BYTESMAXTRANSFER _PARMNUM | wki_use_512_bytes_max_transfer


Platform Support

The Net functions are implemented on all Win32 platforms. However, there are implementation differences between the platforms. The following sections contain platform-specific information.

  • Windows 95 support
  • Functions that only have support for remoting to LAN Manager 2.x
  • Requests from 16-bit LAN Manager clients
  • Calling 16-bit LAN Manager servers


Windows 95 Support

The following Net functions are supported by Windows 95 and Windows 98:

NetAccessAdd
NetAccessCheck
NetAccessDel
NetAccessEnum
NetAccessGetInfo
NetAccessGetUserPerms
NetAccessSetInfo
NetConnectionEnum
NetFileEnum
NetServerGetInfo
NetSessionDel
NetSessionEnum
NetSessionGetInfo
NetShareAdd
NetShareDel
NetShareEnum
NetShareGetInfo
NetShareSetInfo


Functions That Only Have Support for Remoting to LAN Manger 2.x

Functions That Only Have Support for Remoting to LAN Manager 2.x

The following groups of functions only have support for remoting to a LAN Manager 2.x computer.

  • Access functions
  • Audit functions
  • Configuration functions
  • Error logging functions


Requests from 16-bit LAN Manager Clients

Windows NT provides support for most remote functions called from LAN Manager 2.x clients. However, the following calls are not supported when they are accessed with a LAN Manager 2.x client to a Windows NT server. In some of the following, there is a more current version of the function that is supported.

  • DosPrintDriverEnum
  • DosPrintQProcessorEnum
  • DosPrintPortEnum
  • DosPrintDest
  • NetAccessCheck
  • NetAlertRaise
  • NetAlertStart
  • NetAlertStop
  • NetAuditClear
  • NetAuditOpen
  • NetAuditRead
  • NetAuditWrite
  • NetConfigGet2
  • NetConfigGetAll2
  • NetConfigSet
  • NetErrorLogOpen
  • NetErrorLogClear
  • NetFileClose
  • NetFileEnum
  • NetFileGetInfo
  • NetHandleGetInfo
  • NetHandleSetInfo
  • NetMessageFileSend
  • NetMessageLogFileSet
  • NetMessageLogFileGet
  • NetMessageNameFwd
  • NetMessageNameUnFwd
  • NetNetBiosEnum
  • NetNetBiosGetInfo
  • NetProfileSave
  • NetProfileLoad
  • NetServerAdminCommand
  • NetServerEnum
  • NetServiceStatus
  • NetStatisticsGet
  • NetStatisticsClear
  • NetUseAdd
  • NetUseDel
  • NetUseEnum
  • NetUseGetInfo
  • NetUserAdd
  • NetUserSetInfo
  • NetUserValidate2
  • NetWkstaSetUID


Calling 16-bit LAN Manager Servers

When an RPC-based function fails to connect to the appropriate interface, the client-side stub may attempt to initiate a function request to activate the selected server. For most of the Win32 networking functions specified in this document, and any API where the functionality and data formats are changed only for 32-bit usage, the conversion is straightforward. For components that offer new functionality the caller of the function should generally be aware of the destination type. When the new function offers a superset of the functionality of the LAN Manager 2.x station the same function is used for both destinations, but the new function members must have either a reserved value of an associated field to inform the conversion layer the field may be ignored if going LAN Manager 2.x systems. This is required so that a function caller is not misled as to the action performed when the function was called.


Using Net Functions

This section discusses how to use the Net functions in your application.

  • 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
  • Determining the Validating Server on Windows 95
  • Looking up text for error code numbers


Looking Up a User's Full Name

Computers running Windows NT can be organized into a domain, which is a collection of computers on a Windows NT Server 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 on Windows NT:

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

#include <windows.h>
#include <lm.h>
#include <stdio.h>

BOOL GetFullName( char *UserName, char *Domain, char *dest )
{
    WCHAR wszUserName[256];          // Unicode user name
    WCHAR wszDomain[256];
    LPBYTE ComputerName;

    struct _SERVER_INFO_100 *si100;  // Server structure
    struct _USER_INFO_2 *ui;         // User structure

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

    NetGetDCName( NULL, wszDomain, &ComputerName );

// Look up the user on the DC.

    if( NetUserGetInfo( (LPWSTR) ComputerName,
        (LPWSTR) &wszUserName, 2, (LPBYTE *) &ui ) )
    {
        printf( "Error getting user information.\n" );
        return( FALSE );
    }

// Convert the Unicode full name to ANSI.

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

    return (TRUE);
}


Forcing a User to Change the Logon Password

Windows NT

This code sample demonstrates how to force a user to change the logon password on the next logon using the NetUserGetInfo and NetUserSetInfo functions and the USER_INFO_3 structure.

Set the usri3_password_expired member of the USER_INFO_3 structure to a nonzero value using the following code fragment:

#define UNICODE
#include <windows.h>
#define INCL_NET
#include <lm.h>

#define USERNAME TEXT("your_user_name")
#define SERVER TEXT(\\\\server)

void main( void )
{
         PUSER_INFO_3 pUsr;
         DWORD netRet = 0, dwParmError = 0;
//
// First, retrieve the user information at level 3.  This is necessary
// to prevent resetting other user information when the NetUserSetInfo
// call is made.
//
NetRet = NetUserGetInfo( SERVER, USERNAME, 3, &pUsr);
 if( netRet == NERR_Success )
 {
//
// The function was successful, now, set the usri3_password_expired value
// to a nonzero value.
// Call NetUserSetInfo.
//
pUsr->usri3_password_expired = TRUE;
netRet = NetUserSetInfo( PDC, USERNAME, 3, pUsr, &dwParmError);
//
// A zero return indicates success.   If the return value is
// ERROR_INVALID_PARAMETER
// then the dwParmError variable will contain a value representing an
// invalid parameter within the user_info_3 structure.  These values
// are defined in the lmaccess.h file in the Values for ParmError for //NetUserSetInfo Section.
//
if( netRet == NERR_Success )
     printf("User %S will need to change password at next logon", USERNAME);
else printf("Error %d occurred.  Parm Error %d returned.\n", netRet, dwParmError);
//
// Must free the buffer returned by NetUserGetInfo…
//
NetApiBufferFree( pUsr);
}
else printf("NetUserGetInfo failed: %d\n",netRet);


Changing Elements of User Information

Windows NT

The code sample in this topic demonstrates how to change several elements of user information using the NetUserGetInfo and NetUserSetInfo functions and various levels of several structures.

The Net functions provide a variety of levels to assist in changing user information. Some of these levels require administrative privileges to execute successfully. When changing user information, it is best to use the specific level for that piece of information. This prevents the accidental resetting of unrelated information when using the lower level values. Some of the more commonly used levels are illustrated in the following sample code.

All code fragments assume that the user has defined the UNICODE compile directive and included the appropriate Net function header files, as follows:

#define UNICODE
#include <windows.h>
#define INCL_NET
#include <lm.h>

Setting the User Password, Level 1003

This level sets the password to a known value. The USER_INFO_1003 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

#define PASSWORD TEXT("new_password")

.
.
.
USER_INFO_1003 usriSetPassword;
DWORD netRet = 0;
//
// Set the usri1003_password element to point to a Unicode string
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriSetPassword.usri1003_password  = PASSWORD;
netRet = NetUserSetInfo( SERVER, USERNAME,  1003, (LPBYTE)&usriSetPassword);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Privilege, Level 1005

This level sets the privilege level of the user. The USER_INFO_1005 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

USER_INFO_1005 usriPriv;
DWORD netRet = 0;
//
// Set the usri1005_priv to the appropriate value, then call NetUserSetInfo.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriPriv.usri1005_priv  = USER_PRIV_USER;
netRet = NetUserSetInfo( SERVER, USERNAME,  1005, (LPBYTE)&usriPriv);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Home Directory, Level 1006

This level sets the user home directory. The USER_INFO_1006 structure topic contains a description of each flag. This directory can be a hard coded path or a valid Unicode path.

#define HOMEDIR TEXT("C:\\USER\USER_PATH")
USER_INFO_1006 usriHomeDir;
//
// Set the usri1006_home_dir to point to a valid Unicode string for the new home directory.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriHomeDir.usri1006_home_dir  = HOMEDIR;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriHomeDir);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Comment Field, Level 1007

This level is used to set the user comment field. The USER_INFO_1007 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

#define COMMENT TEXT("This is my Comment Text for the user")
USER_INFO_1007 usriComment;
//
// Set the usri1007_comment  to point to a valid Unicode string for the new comment.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriComment.usri1007_comment  = COMMENT;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriComment);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Flags, Level 1008

This level sets the user flags. The USER_INFO_1008 structure topic contains the valid values for the flags field. The UF_SCRIPT flag must be set for Windows NT and LAN Manager networks. Trying to set the flags without setting this bit on a Windows NT or LAN Manager network will cause the NetUserSetInfo function to fail. The following code fragment illustrates how to use this level.

#define USR_FLAGS UF_SCRIPT | UF_NORMAL_ACCOUNT
USER_INFO_1008 usriFlags;
//
// Set the usri1008_flags  to the appropriate constant.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriFlags.usri1008_flags  = USR_FLAGS;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriFlags);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Script Path, Level 1009

This level is used to set a logon script path for a particular user. Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null. The USER_INFO_1009 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

#define SCRIPT_PATH "C:\\BIN\\MYSCRIPT.BAT"
USER_INFO_1009 usriScrPath;
//
// Set the usri1009_script_path  to a Unicode string constant or a pointer to a Unicode string.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriScrPath.usri1009_script_path  = SCRIPT_PATH;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriScrPath);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting The User Authority Flags, Level 1010

This level is used to set the authority flags for a user. The USER_INFO_1010 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

#define AUTHORITY_FLAGS AF_OP_ACCOUNTS
USER_INFO_1010 usriAuthFlags;
//
// Set the usri1010_auth_flags  a constant containing the appropriated flag values.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriAuthFlags.usri1010_auth_flags  = SCRIPT_PATH;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriAuthFlags);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting The User Full Name, Level 1011

This level sets the user's full name. The USER_INFO_1011 structure topic contains a description of each flag. The following code fragment illustrates how to use this level.

#define USER_FULL_NAME TEXT("Joe B. User")
USER_INFO_1011 usriFullName;
//
// Set the usri1011_full_name  to a Unicode string constant or a pointer to a Unicode string.
//
// SERVER and USERNAME can be hard coded TEXT("") strings or pointers to
// Unicode strings.
//
usriFullName.usri1011_full_name  = USER_FULL_NAME;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriFullName);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);


Creating a New Computer Account

Windows NT

This code sample demonstrates how to create a new computer account in Windows NT using the NetUserAdd function.

The following are considerations for managing computer accounts:

  • The computer account name should be all uppercase for consistency with Windows NT account management utilities.
  • A computer account name always has a trailing dollar sign ($). Any functions used to manage computer accounts must build the computer name such that the last character of the computer account name is a dollar sign ($). For interdomain trust, the account name is TrustingDomainName$.
  • The maximum computer name length is MAX_COMPUTERNAME_LENGTH (15). This length does not include the trailing dollar sign ($).
  • The password for a new computer account should be the lowercase representation of the computer account name, without the trailing dollar sign ($). For interdomain trust, the password can be an arbitrary value that matches the value specified on the trust side of the relationship.
  • The maximum password length is LM20_PWLEN (14). The password should be truncated to this length if the computer account name exceeds this length.
  • The password provided at computer-account-creation time is valid only until the computer account becomes active on the domain. A new pasword is established during trust relationship activation.
#include <windows.h>
#include <lm.h>

BOOL AddMachineAccount(
    LPWSTR wTargetComputer,
    LPWSTR MachineAccount,
    DWORD AccountType
    )
{
    LPWSTR wAccount;
    LPWSTR wPassword;
    USER_INFO_1 ui;
    DWORD cbAccount;
    DWORD cbLength;
    DWORD dwError;

    //
    // Ensure a valid computer account type was passed.
    //
    if (AccountType != UF_WORKSTATION_TRUST_ACCOUNT &&
        AccountType != UF_SERVER_TRUST_ACCOUNT &&
        AccountType != UF_INTERDOMAIN_TRUST_ACCOUNT
        )
    {
        SetLastError(ERROR_INVALID_PARAMETER);
        return FALSE;
    }

    //
    // Obtain number of chars in computer account name.
    //
    cbLength = cbAccount = lstrlenW(MachineAccount);

    //
    // Ensure computer name doesn't exceed maximum length.
    //
    if(cbLength > MAX_COMPUTERNAME_LENGTH) {
        SetLastError(ERROR_INVALID_ACCOUNT_NAME);
        return FALSE;
    }

    //
    // Allocate storage to contain Unicode representation of
    // computer account name + trailing $ + NULL.
    //
    wAccount=(LPWSTR)HeapAlloc(GetProcessHeap(), 0,
        (cbAccount + 1 + 1) * sizeof(WCHAR)  // Account + '$' + NULL
        );

    if(wAccount == NULL) return FALSE;

    //
    // Password is the computer account name converted to lowercase
    // you will convert the passed MachineAccount in place.
    //
    wPassword = MachineAccount;

    //
    // Copy MachineAccount to the wAccount buffer allocated while
    // converting computer account name to uppercase.
    // convert password (inplace) to lowercase.
    //
    while(cbAccount--) {
        wAccount[cbAccount] = towupper( MachineAccount[cbAccount] );
        wPassword[cbAccount] = towlower( wPassword[cbAccount] );
    }

    //
    // Computer account names have a trailing Unicode '$'.
    //
    wAccount[cbLength] = L'$';
    wAccount[cbLength + 1] = L'\0'; // terminate the string

    //
    // If the password is greater than the max allowed, truncate.
    //
    if(cbLength > LM20_PWLEN) wPassword[LM20_PWLEN] = L'\0';

    //
    // Initialize USER_INFO_x structure.
    //
    ZeroMemory(&ui, sizeof(ui));

    ui.usri1_name = wAccount;
    ui.usri1_password = wPassword;

    ui.usri1_flags = AccountType | UF_SCRIPT;
    ui.usri1_priv = USER_PRIV_USER;

    dwError=NetUserAdd(
                wTargetComputer,    // target computer name
                1,                  // info level
                (LPBYTE) &ui,       // buffer
                NULL
                );

    //
    // Free allocated memory.
    //
    if(wAccount) HeapFree(GetProcessHeap(), 0, wAccount);

    //
    // Indicate whether the function was successful.
    //
    if(dwError == NO_ERROR)
        return TRUE;
    else {
        SetLastError(dwError);
        return FALSE;
    }
}

The user that calls the account management functions must have Administrator privilege on the target computer. In the case of existing computer accounts, the creator of the account can manage the account, regardless of administrative membership.

The SeMachineAccountPrivilege can be granted on the target computer to give specified users the ability to create computer accounts. This gives non-administrators the ability to create computer accounts. The caller needs to enable this privilege prior to adding the computer account.


Creating a Local Group and Adding a User

Windows NT

Windows NT and the Windows NT Server use the same functions that Microsoft LAN Manager uses to create and maintain user and local group-account information. A member of a Users group can create, maintain, and delete accounts in local groups. For example, to create a new local group, use the NetLocalGroupAdd function. To add a user to that group, use the.NetLocalGroupAddMembers function.

The following program allows you to create a user and a local group and add the user to the local group.

#define UNICODE 1
#include <windows.h>
#include <lmcons.h>
#include <lmaccess.h>
#include <lmerr.h>
#include <lmapibuf.h>
#include <stdio.h>
#include <stdlib.h>

int _CRTAPI1 main( int cArgs, char *pArgs[] );

NET_API_STATUS NetSample( LPWSTR lpszDomain,
                          LPWSTR lpszUser,
                          LPWSTR lpszPassword,
                          LPWSTR lpszLocalGroup )
{

    USER_INFO_1               user_info;
    LOCALGROUP_INFO_1         localgroup_info;
    LOCALGROUP_MEMBERS_INFO_3 localgroup_members;
    LPWSTR                    lpszPrimaryDC = NULL;
    NET_API_STATUS            err = 0;
    DWORD                     parm_err = 0;

/* First get the name of the Primary Domain Controller. */
/* Be sure to free the returned buffer */

    err = NetGetDCName( NULL,                    /* Local Machine */
                   lpszDomain,                  /* Domain Name */
                   (LPBYTE *)&lpszPrimaryDC );  /* returned PDC */

    if ( err != 0 )
    {
        printf( "Error getting DC name: %d\n", err );
        return( err );
    }

/* Set up the USER_INFO_1 struct */

    user_info.usri1_name = lpszUser;
    user_info.usri1_password = lpszPassword;
    user_info.usri1_priv = USER_PRIV_USER;
    user_info.usri1_home_dir = TEXT("");
    user_info.usri1_comment = TEXT("Sample User");
    user_info.usri1_flags = UF_SCRIPT;
    user_info.usri1_script_path = TEXT("");

    err = NetUserAdd( lpszPrimaryDC,       /* PDC name */
                      1,                   /* level */
                      (LPBYTE)&user_info,  /* input buffer */
                      &parm_err );         /* parameter in error */

    switch ( err )
    {
    case 0:
        printf("user successfully created.\n");
        break;
    case NERR_UserExists:
        printf("user already exists.\n");
        err = 0;
        break;
    case ERROR_INVALID_PARAMETER:
        printf("Invalid Parameter Error adding user:
        Parameter Index = %d\n",
                parm_err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    default:
        printf("Error adding user: %d\n", err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    }

/* Set up the LOCALGROUP_INFO_1 struct */

    localgroup_info.lgrpi1_name = lpszLocalGroup;
    localgroup_info.lgrpi1_comment = TEXT("Sample Local group.");

    err = NetLocalGroupAdd( lpszPrimaryDC,    /* PDC name */
                  1,                          /* level */
                  (LPBYTE)&localgroup_info,   /* input buffer */
                  &parm_err );                /* parm in error */

    switch ( err )
    {
    case 0:
        printf("Local Group successfully created.\n");
        break;
    case ERROR_ALIAS_EXISTS:
        printf("Local Group already exists.\n");
        err = 0;
        break;
    case ERROR_INVALID_PARAMETER:
        printf("Invalid Parameter Error adding Local Group:
        Parameter Index = %d\n",
                err, parm_err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    default:
        printf("Error adding Local Group: %d\n", err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    }

/* Now add the user to the local group */

    localgroup_members.lgrmi3_domainandname = lpszUser;

    err = NetLocalGroupAddMembers( lpszPrimaryDC,     /* PDC name */
                           lpszLocalGroup,    /* group name */
                           3,           /* passing in name */
                           LPBYTE)&localgroup_members, /* Buffer */
                           1 );                  /* count passed in */

    switch ( err )
    {
    case 0:
        printf("User successfully added to Local Group.\n");
        break;
    case ERROR_MEMBER_IN_ALIAS:
        printf("User already in Local Group.\n");
        err = 0;
        break;
    default:
        printf("Error adding User to Local Group: %d\n", err);
        break;
    }

    NetApiBufferFree( lpszPrimaryDC );
    return( err );
}

int _CRTAPI1 main( int    cArgs,
                   char * pArgs[] )
{
    NET_API_STATUS err = 0;

    printf( "Calling NetSample.\n" );
    err = NetSample( TEXT("SampleDomain"),
                     TEXT("SampleUser"),
                     TEXT("SamplePswd"),
                     TEXT("SampleLG") );
    printf( "NetSample returned %d\n", err );
    return( 0 );
}


Determining the Validating Server on Windows 95

Windows 95 and Windows 98

The code sample in this topic demonstrates how to determine the validating server on Windows 95, using the Net functions.

Determining the Windows NT Domain server that validate a user's logon password from a Windows 95 or Windows 98 workstation is an involved task. On Windows NT, the 32-bit NetWkstaUserGetInfo function determines the validating server. The function uses level 1 to return a WKSTA_USER_INFO_1 structure. The wkui1_logon_server member will contain a pointer to a Unicode string containing the validating server.

On Windows 95 and Windows 98, there is no 32-bit function that will return the same information. You must use the 16-bit Net functions to retrieve the same information. The functions are exported from NETAPI.DLL. The link libraries are included with the 16-bit version of Microsoft® Visual C++ ( version 1.5x ).

Use the following basic steps to determine the validating server:

  1. Determine the user's logon domain using NetWkstaGetInfo.
  2. Find the Primary Domain Controller (PDC) using NetGetDCName.
  3. Get the user information from the PDC for comparison to the Backup Domain Controller (BDC) data using NetUserGetInfo.
  4. Get a list of BDCs using the NetServerEnum2 function.
  5. Loop through the list of BDCs, using NetUserGetInfo to retrieve the specific user information, comparing each last logon time, searching for the greatest value.

The largest last logon value will be the latest logon time, this will be the last server to validate the user's logon password.

The following short 16-bit program illustrates how to determine the validating server for a Windows 95 user.

You must use the LAN.H and the NETAPI.LIB files distributed with the SDK to work. The user must be certain that the directories for the .H and .LIB files are in the search path for the project.

Global Variables:

  • Users. Pointer to the USER_INFO_11 structure that contains user information about the username derived from the Wksta array. The elements of interest:
    usi11_last_logon - seconds since Jan 1, 1970. Time that this server last validated this user's logon password.
  • Wksta. Pointer to the WKSTA_INFO_10 structure that contains information about the WFW workstation. This structure is filled first and the information placed therein is used to get additional information.The domain name is used to get a list of BDCs that will be queried for user data. The username is the element that will qualify the user data request. The information of interest:
    wki10_username - the current logged-on user.
    wki10_logon_domain - the domain the user logged onto.
  • Servers. List of backup domain controllers for the user's logon domain. Each server in the array will be queried for information about the current logged-on user as described in the user's variable comments.
*/
#include <windows.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <time.h>
#define INCL_NET
#include <lan.h>
//
// Constant definitions
//
#define LEVEL_01 1
#define LEVEL_11 11
#define LEVEL_10 10
#define LEVEL_00 0

#define SMALL_BUFFER 1024
#define MEDIUM_BUFFER 4*1024
#define SERVER_NAME  50
//
// Buffer allocation.  Just doing it global for simplicity
//
LPSTR bdcNames[SMALL_BUFFER];
LPSTR UserData[MEDIUM_BUFFER];
LPSTR WrkSta[SMALL_BUFFER];
LPSTR pdcName[SERVER_NAME];
LPSTR servername[SERVER_NAME];
//
// Create a structure to hold the current server and the logon time
// So the values are together.
//
typedef struct svr_usr {
        LPSTR server;
        long logon_time;
        } SVR_USR;
//
// Create typedefs for the larger structure names to shorten
// the number of chars to type.
//
typedef struct user_info_11  USER11;
typedef struct wksta_info_10 WORK10;
typedef struct wksta_info_1 WORK01;
typedef struct server_info_100 SERVER100;
typedef struct tm TIMER;
//
// Declare pointers so the buffers returned from the system
// APIs can be caste to the appropriate value.
//
TIMER  *lpTime;
USER11  far *Users;
WORK10  far *Wksta;
SERVER0 far *Servers;
WORK01  far *Wksta01;

char * lpszTime;

//
// Declare some short values for use with the LAN Man APIs
//
unsigned short svrEntries;
unsigned short svrRead;
unsigned short usrEntries;
unsigned short wkstaEntries;
//
// Setup a temp var to use as a loop control var
//
unsigned short i;

char Message[256];
//
// define a global var to hold the validating server and the time
// the user last logged in.
//
SVR_USR validate = { NULL, 0 };
//
// Global var for the return value of the LAN Man API used in
// error checking.
//
DWORD netRet;
//
// Bogus WinMain so you can step through the example in VC 1.52
// debugger.
//
int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow)
HANDLE hInstance;                /* current instance         */
HANDLE hPrevInstance;            /* previous instance        */
LPSTR lpCmdLine;                 /* command line             */
int nCmdShow;                    /* show-window type (open/icon) */
{
   //
   // First, Get the workstation information using NetWkstaGetInfo
   // at level 10.  This will return the Domain the user logged into
   //
   netRet = NetWkstaGetInfo( NULL,     // This workstation
                             LEVEL_10, // Level of Info requested.
                             (char far *)WrkSta,   // Buffer
                             SMALL_BUFFER,
                             &wkstaEntries); // Expecting only 1 entrie

   if( netRet != NERR_Success )
   {
      //
      // A network error occured.  Print it to the stdout
      //
      sprintf(Message,"ERROR: NetWkstaGetInfo API Failed. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetWkstaGetInfo Error", MB_OK);
      return(0);
   }
   //
   // Success, we have workstation information.
   // Now we must retrieve the backup domain controllers and the
   // primary domain controller to check to see when the user last
   // logon was validated.
   // The argument list is set as follows:
   //  Execute on the local machine ( NULL )
   //  Pass the domain name of interest (Wksta[0].wki10_logon_domain)
   //  Pass a buffer to receive the domain controller name
   //  Pass the size of the DC name buffer
   //
   Wksta = (WORK10 *)WrkSta;
   netRet = NetGetDCName( NULL,
                          Wksta[0].wki10_logon_domain,
                          (char far *)pdcName,
                          SERVER_NAME);
   if(netRet != NERR_Success )
   {
      //
      // Could not locate a PDC.  Something is wrong, terminate Prog.
      //
      sprintf(Message,"ERROR: NetGetDCName API Failed. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetGetDCName Error", MB_OK);
      return(0);
   }
   //
   // We have the primary domain controller. Lets query it for the
   // users information, then store it temprarily for comparison
   // to the BDC's (Backup Domain Controller) data.
   //
   //
   netRet = NetUserGetInfo( (char far *)pdcName,  // Execute on the PDC
                            Wksta[0].wki10_username, // User's name
                            LEVEL_11,
                            (char far *)UserData, // Put strucs here
                            SMALL_BUFFER,
                            &usrEntries); // expecting only one entry
   if( netRet != NERR_Success )
   {
       //
       // No user account on the PDC.  Something does not jive.
       // terminate program.
       //
      sprintf(Message,"ERROR: NetUserGetInfo API Failed on PDC. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetUserGetInfo Error", MB_OK);
      return(0);
   }
   //
   // Set the structure so that the PDC is the starting validating server
   //
   validate.server =  (char far *)pdcName;
   Users = (USER11 * )UserData;
   validate.logon_time = Users[0].usri11_last_logon;
   //
   // Now retrieve all of the BDC's
   //
   netRet = NetServerEnum2(  NULL,
                             LEVEL_00,
                             (char far *)bdcNames,
                             SMALL_BUFFER,
                             &svrRead,
                             &svrEntries,
                             SV_TYPE_DOMAIN_BAKCTRL,
                             Wksta[0].wki10_logon_domain);

   if( netRet != NERR_Success )
   {
      //
      // OOPS, no BDC's.  That could be an error
      //
      sprintf(Message,"ERROR: NetServerEnum2 API Failed. Error Code: %d", netRet);
      MessageBox( NULL, Message, "NetServerEnum2", MB_OK);
      return( 0 );
   }
   //
   // Great, we have a list of backup domain controllers
   // if svrEntries > 1.
   //
   // Loop through the list checking to the last logon time against the
   // one currently stored in validate.logon_time
   //
   Servers =( SERVER0 * )bdcNames;
   for( i = 0; i < svrEntries; i++ )
   {
       //
       // Must add the \\ to the names returned from NetServerEnum()
       //
       _fstrcpy( (LPSTR)servername,"\\\\");
       _fstrcat( (LPSTR)servername,Servers[i].sv0_name);
       netRet = NetUserGetInfo( (LPSTR)servername,  // Execute on a BDC
                               Wksta[0].wki10_username, // User's name
                               LEVEL_11,
                               (char far *)UserData,
                               SMALL_BUFFER,
                               &usrEntries); // expecting only one entry
       Users = (USER11 *)UserData;
       if( netRet == NERR_Success )
       {
          //
          // Great, we found a user entry on this BDC.  Compare his
          // last logon time to the stored time.  Replace the stored time
          // if the time is greater.
          // Replace the servername so the time and the server match.
          //
          if( Users[0].usri11_last_logon > validate.logon_time)
          {
             validate.server = (char far *)&Servers[i];
             validate.logon_time = Users[0].usri11_last_logon;
          }
          else if( Users[0].usri11_last_logon == validate.logon_time )
          {
             //
             // Just to let you know that this could indicate a problem
             //
             sprintf(Message,"Values are the same. %ls %ls", Servers[i].sv0_name, validate.server);
             MessageBox( NULL, Message, "HMMMM...........",MB_OK);
          }
       }
    }
    //
    // Convert the time in seconds to the a time structure for display and
    // build the output string.
    //
    lpTime = gmtime( &validate.logon_time);
    lpszTime = asctime( lpTime );
    _fstrcpy((LPSTR)Message, (LPSTR)"Username: ");
    _fstrcat((LPSTR)Message, (LPSTR)Wksta[0].wki10_username);
    _fstrcat((LPSTR)Message, (LPSTR)"\nLast Logon: ");
    _fstrcat((LPSTR)Message, (LPSTR)lpszTime);
    _fstrcat((LPSTR)Message, (LPSTR)"Logon Server: ");
    _fstrcat((LPSTR)Message, (LPSTR)validate.server);
    //
    // Display the information.
    //
    MessageBox(NULL,Message,"Logon Validation Information", MB_OK);
    return(0);
}


Looking Up Text for Error Code Numbers

Windows NT

In Windows NT, it is sometimes necessary to display error text associated with error codes returned from networking related functions. You may need to perform this task with the family of Net functions in Windows NT.

The error text for these messages is found in the message table file named Netmsg.dll, which is found in %systemroot%\system32. This file contains error messages in the range NERR_BASE (2100) through MAX_NERR(NERR_BASE+899). These error codes are defined in the Windows NT Net function header file lmerr.h.

The LoadLibrary and LoadLibraryEx Win32 functions can load Netmsg.dll. The FormatMessage Win32 function maps an error code to message text, given a module handle to the Netmsg.dll file.

The following sample illustrates how to display error text associated with Net-related functions, in addition to displaying error text associated with system-related error codes. If the supplied error number is in a specific range, the netmsg.dll message module is loaded and used to look up the specified error number with the FormatMessage function.

#include <windows.h>
#include <stdio.h>

#include <lmerr.h>

void
DisplayErrorText(
    DWORD dwLastError
    );

#define RTN_OK 0
#define RTN_USAGE 1
#define RTN_ERROR 13

int
__cdecl
main(
    int argc,
    char *argv[]
    )
{
    if(argc != 2) {
        fprintf(stderr,"Usage: %s <error number>\n", argv[0]);
        return RTN_USAGE;
    }

    DisplayErrorText( atoi(argv[1]) );

    return RTN_OK;
}

void
DisplayErrorText(
    DWORD dwLastError
    )
{
    HMODULE hModule = NULL; // default to system source
    LPSTR MessageBuffer;
    DWORD dwBufferLength;

    DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER |
        FORMAT_MESSAGE_IGNORE_INSERTS |
        FORMAT_MESSAGE_FROM_SYSTEM ;

    //
    // if dwLastError is in the network range, load the message source
    //

    if(dwLastError >= NERR_BASE && dwLastError <= MAX_NERR) {
        hModule = LoadLibraryEx(
            TEXT("netmsg.dll"),
            NULL,
            LOAD_LIBRARY_AS_DATAFILE
            );

        if(hModule != NULL)
            dwFormatFlags |= FORMAT_MESSAGE_FROM_HMODULE;
    }

    //
    // call FormatMessage() to allow for message text to be acquired
    // from the system or the supplied module handle
    //

    if(dwBufferLength = FormatMessageA(
        dwFormatFlags,
        hModule, // module to get message from (NULL == system)
        dwLastError,
        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // default language
        (LPSTR) &MessageBuffer,
        0,
        NULL
        ))
    {
        DWORD dwBytesWritten;

        //
        // Output message string on stderr
        //
        WriteFile(
            GetStdHandle(STD_ERROR_HANDLE),
            MessageBuffer,
            dwBufferLength,
            &dwBytesWritten,
            NULL
            );

        //
        // free the buffer allocated by the system
        //
        LocalFree(MessageBuffer);
    }

    //
    // if we loaded a message source, unload it
    //
    if(hModule != NULL)
        FreeLibrary(hModule);
}

After you compile this program, you can insert the error code number as an argument and the program will display the text. For example:

C:\> netmsg 2453
Could not find domain controller for this domain


Net Functions Reference

The Net functions reference section consists of descriptions for Net functions and their associated data structures.


Net Functions

The Net functions consist of Alert, API Buffer, Directory Services, Distributed File System (DFS), File, Get, Group, Handle, Local Group, Message, Remote Utility, Schedule, Server, Session, Share, Statistics, User, and Workstation functions.

Alert Functions

NetAlertRaise
NetAlertRaiseEx

API Buffer Functions

NetApiBufferAllocate
NetApiBufferFree
NetApiBufferReallocate
NetApiBufferSize

Directory Service Functions

DsGetDcName
DsGetSiteName
DsValidateSubnetName

Distributed File System (Dfs) Functions

NetDfsAdd
NetDfsEnum
NetDfsGetInfo
NetDfsRemove
NetDfsSetInfo

Net File Functions

NetFileEnum
NetFileGetInfo

Get Functions

MultinetGetConnectionPerformance
NetGetAnyDCName
NetGetDCName
NetGetDisplayInformationIndex
NetQueryDisplayInformation

Group Functions

NetGroupAdd
NetGroupAddUser
NetGroupDel
NetGroupDelUser
NetGroupEnum
NetGroupGetInfo
NetGroupGetUsers
NetGroupSetInfo
NetGroupSetUsers

Handle Functions

NetHandleGetInfo
NetHandleSetInfo

Local Group Functions

NetLocalGroupAdd
NetLocalGroupAddMembers
NetLocalGroupDel
NetLocalGroupDelMembers
NetLocalGroupEnum
NetLocalGroupGetInfo
NetLocalGroupGetMembers
NetLocalGroupSetInfo
NetLocalGroupSetMembers

Message Functions

NetMessageBufferSend
NetMessageNameAdd
NetMessageNameDel
NetMessageNameEnum
NetMessageNameGetInfo

Remote Utility Function

NetRemoteTOD

Replicator Functions

NetReplExportDirAdd
NetReplExportDirDel
NetReplExportDirEnum
NetReplExportDirGetInfo
NetReplExportDirLock
NetReplExportDirSetInfo
NetReplExportDirUnlock
NetReplGetInfo
NetReplImportDirAdd
NetReplImportDirDel
NetReplImportDirEnum
NetReplImportDirGetInfo
NetReplImportDirLock
NetReplImportDirUnlock
NetReplSetInfo

Schedule Functions

NetScheduleJobAdd
NetScheduleJobDel
NetScheduleJobEnum
NetScheduleJobGetInfo

Server Functions

NetServerDiskEnum
NetServerEnum
NetServerGetInfo
NetServerSetInfo
NetServerTransportAdd
NetServerTransportDel
NetServerTransportEnum

Session Functions

NetSessionDel
NetSessionEnum
NetSessionGetInfo

Share Functions

NetShareAdd
NetShareCheck
NetShareDel
NetShareGetInfo
NetShareSetInfo

Statistics Function

NetStatisticsGet2

User Functions

NetUserAdd
NetUserChangePassword
NetUserDel
NetUserEnum
NetUserGetGroups
NetUserGetInfo
NetUserGetLocalGroups
NetUserSetGroups
NetUserSetInfo
NetUserModalsGet
NetUserModalsSet

Workstation and Workstation User Functions

NetWkstaGetInfo
NetWkstaSetInfo
NetWkstaTransportAdd
NetWkstaTransportDel
NetWkstaTransportEnum
NetWkstaUserGetInfo
NetWkstaUserSetInfo
NetWkstaUserEnum

Obsolete Functions

NetAccessAdd
NetAccessCheck
NetAccessDel
NetAccessEnum
NetAccessGetInfo
NetAccessGetUserPerms
NetAccessSetInfo
NetAuditClear
NetAuditRead
NetConfigGet
NetConfigGetAll
NetConfigSet
NetConnectionEnum
NetErrorLogClear
NetErrorLogRead
NetFileClose
NetLocalGroupAddMember
NetLocalGroupDelMember
NetServiceControl
NetServiceEnum
NetServiceGetInfo
NetServiceInstall
NetShareEnum
NetStatisticsGet
NetUseAdd
NetUseDel
NetUseEnum
NetUseGetInfo


DsGetDcName

[This is preliminary documentation and subject to change.]

The DsGetDcName function returns the name of a domain controller (DC) in a specified domain. You can supply DC selection criteria are to this function to indicate preference for a DC with particular characteristics.

DWORD DsGetDcName(
  LPCTSTR ComputerName,
  LPCTSTR DomainName,
  GUID *DomainGuid,
  LPCTSTR SiteName,
  ULONG Flags,
  PDOMAIN_CONTROLLER_INFO *DomainControllerInfo
);

Parameters

ComputerName
Pointer to a null-terminated string that specifies the name of the remote server to process this function. Typically, this parameter should be specified as NULL.
DomainName
Pointer to a null-terminated string that specifies the name of the domain to query. This name can either be a DNS-style name (for example, microsoft.com.) or a flat-style name (for example, microsoft). If a DNS-style name is specified, the name may be specified with or without a trailing period.

If NULL is specified and the DS_GC_SERVER_REQUIRED flag is specified, DomainName defaults to the tree name of the primary domain of ComputerName.

If NULL is specified and the DS_GC_SERVER_REQUIRED flag is not specified, DomainName defaults to the domain name of the primary domain of ComputerName.

DomainGuid
Pointer to a GUID structure that specifies the Domain GUID of the domain being queried. This value renames the domain. That is, if this value is specified and DomainName has been renamed, DsGetDcName attempts to locate a DC in the domain having the GUID specified by DomainGuid.
SiteName
Pointer to a null-terminated string that specifies the name of the site the returned DC should be physically near. The parameter should typically be the name of the site where the client is located. If not specified, SiteName defaults to the site of ComputerName.
Flags
Passes additional information to be used to process the request. This parameter can be a combination of the following values.
Value | Meaning
DS_FORCE_REDISCOVERY | Use this flag when an additional domain controller becomes available or where a domain controller has been detected to be unavailable. This function only guarantees the DC returned when the DC was initially entered into the cache. Do not specify this flag unless you have recently called this function without this flag. You should attempt to access the cached domain controller. Only if that access fails should you call again with this flag.
DS_DIRECTORY_SERVICE_REQUIRED | Requires that the returned DC support Windows NT 5.0 or later.
DS_DIRECTORY_SERVICE_PREFERRED | Prefers that the returned DC support directory service functions (Windows NT 5.0 or later). If no such DC is available, an earlier version of the DC returns. If a DC that supports a DS is not available, DsGetDcName returns the name of a non-DS DC. However, DsGetDcName returns only the non-DS DC information after the attempt to find a DS DC times out.
DS_GC_SERVER_REQUIRED | Requires that the returned DC be a global catalog (GC) server for the tree of domains with this domain as the root. This flag may not be set if any of the following flags are set: DS_WRITABLE_REQUIRED, DS_FDC_REQUIRED, or DS_PDC_REQUIRED.
DS_PDC_REQUIRED | Requires that the returned DC be the primary domain controller (PDC) for the domain. This flag may not be set if any of the following flags are set: DS_WRITABLE_REQUIRED, DS_FDC_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_WRITABLE_REQUIRED | Requires that the returned DC host a writable copy of the DS (or SAM). If the specified DomainName is a flat name, this flag is the same as DS_PDC_REQUIRED. If the specified DomainName is a DNS name, this flag finds writable DCs. Only the PDC is writable in a Windows NT 5.0 "mixed mode" domain. All DCs are writable in a Windows NT 5.0 "non-mixed mode" domain. In future releases of Windows NT, certain DCs may be configured as "read only"; such DCs are not writableIn future releases of Windows NT, certain DCs may be configured as "read only"; such DCs will not list themselves as writable. This flag may not be set if any of the following flags are set: DS_PDC_REQUIRED, DS_FDC_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_FDC_REQUIRED | Requires that the returned DC be the floating domain controller (FDC) for the domain. In a mixed domain with a Windows NT 3.x or Windows NT 4.0 PDC and one or more Windows NT 5.0 BDCs, one of the Windows NT 5.0 PDCs plays the special role of replicating account changes from the PDC. That DC is called the "floating" DC because the function "floats" to another Windows NT 5.0 BDC automatically if the current FDC becomes unavailable.This flag may not be set if any of the following flags are set: DS_PDC_REQUIRED, DS_WRITABLE_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_IP_REQUIRED | Requires that the IP address of the discovered DC be returned in DomainControllerAddress of the DOMAIN_CONTROLLER_INFO structure.
DS_KDC_REQUIRED | Requires that the returned DC be currently running the Kerberos Key Distribution Center service.
DS_TIMESERV_REQUIRED | Requires that the returned DC be currently running the Windows Time service.
DS_IS_FLAT_NAME | Specifies that the DomainName parameter is a flat name. As such, the IP/DNS compatible locator will not be attempted. This flag may not be specified with the DS_IS_DNS_NAME flag. It is valid to not set DS_IS_FLAT_NAME and DS_IS_DNS_NAME; however, DsGetDcName will take longer to find a DC in that case because it has to search for both the DNS-style and flat name. It is potentially ambiguous to specify neither flag. When this flag is specified, DsGetDcName is NOT search for the DNS-style name of the domain
DS_IS_DNS_NAME | Specifies that the DomainName parameter is a DNS name. This flag may not be specified with the DS_IS_FLAT_NAME flag.

DomainControllerInfo
Pointer to a variable that receives a pointer to a DOMAIN_CONTROLLER_INFO structure describing the domain controller selected. The returned structure must be deallocated using NetApiBufferFree.

Remarks

The DsGetDcName function is sent to the Netlogon service on the remote computer specified by ComputerName.

DsGetDcName does not require any particular access to the specified domain. By default, this function does not ensure that the returned domain controller is currently available. Rather, the caller should attempt to use the returned domain controller. If the domain controller is not available, the caller should repeat the DsGetDcName function, specifying the DS_FORCE_REDISCOVERY flag.

Return Values

If the function returns domain controller information, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NO_SUCH_DOMAIN | No DC is available for the specified domain or the domain does not exist.
ERROR_INVALID_DOMAINNAME | The format of the specified DomainName is invalid.
ERROR_INVALID_COMPUTERNAME | The format of the specified ComputerName is invalid.
ERROR_INVALID_FLAGS | The Flags parameter has conflicting or superfluous bits set.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in dsgetdc.h.
Import Library: Use netapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Networking (Net) Overview, Net Functions, DsGetSiteName, DSValidateSubnetName


DsGetSiteName

[This is preliminary documentation and subject to change.]

The DsGetSiteName function returns the name of the site where a computer resides. For a domain controller (DC), the name of the site is the location of the configured DC. For a member workstation or member server, the name specifies the workstation site as configured in the domain of the computer.

DWORD DsGetSiteName(
  LPCTSTR ComputerName,
  LPTSTR *SiteName
);

Parameters

ComputerName
Pointer to a null-terminated string that specifies the name of the server to send this function. A NULL implies the local computer.
SiteName
Pointer to a variable that receives a pointer to a null-terminated string containing the site location of this computer. The returned buffer must be deallocated using NetApiBufferFree.

Remarks

The DsGetSiteName function does not require any particular access to the specified domain. The function is sent to the Netlogon service on the computer specified by ComputerName.

Return Values

If the function returns account information, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NO_SITENAME | The computer is not in a site.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in dsgetdc.h.
Import Library: Use netapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Networking (Net) Overview, Net Functions, DsGetDcName, DSValidateSubnetName


DsValidateSubnetName

[This is preliminary documentation and subject to change.]

The DsValidateSubnetName function validates a subnet name in the form xxx.xxx.xxx.xxx/YY. The Xxx.xxx.xxx.xxx portion must be a valid IP address. Yy must be the number of leftmost significant bits included in the mask. All bits of the IP address that are not covered by the mask must be specified as zero.

DWORD DsValidateSubnetName(
  LPCTSTR SubnetName
);

Parameters

SubnetName
Pointer to a null-terminated string that specifies the name of the subnet to validate.

Return Values

If the function returns account information, the return value is NO_ERROR.

If the function fails, the return value is the following error code.

Value | Meaning
ERROR_INVALID_NAME | Subnet name is not valid.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in dsgetdc.h.
Import Library: Use netapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Networking (Net) Overview, Net Functions, DsGetDcName, DsGetSiteName


MultinetGetConnectionPerformance

The MultinetGetConnectionPerformance function returns information about the expected performance of a connection used to access a network resource. This function can be used only to request information for a local device that is redirected to a network resource, or for a network resource to which there is currently a connection.

MultinetGetConnectionPerformance(
  LPNETRESOURCE lpNetResource,
  LPNETCONNECTINFOSTRUCT lpNetConnectInfoStruct,
);

Parameters

lpNetResource
Specifies one of the following network resources:
Value | Meaning
lpLocalName | Pointer to a buffer that specifies a local device, such as "F:" or "LPT1", that is redirected to a network resource to be queried. If this parameter is NULL or an empty string, the network resource is specified in lpRemoteName. If this flag specifies a local device, lpRemoteName is ignored.
LpRemoteName | Specifies a network resource to query. The resource must currently have an established connection. For example, if the resource is a file on a file server, then having the file open will ensure the connection.
LpProvider | Usually set to NULL, but may be optionally specified if the network on which the resource resides is known. If lpProvider is not NULL, the system will try only the named network.

lpNetConnectInfoStruct
Pointer to the NETCONNECTINFOSTRUCT structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one or more of the following error values.

Value | Meaning
ERROR_NOT_SUPPORTED | The network resource does not supply this information.
ERROR_NOT_CONNECTED | lpLocalName is not a redirected device, or lpRemoteName is not the name of a resource that is currently connected.
ERROR_NO_NET_OR_BAD_PATH | The operation could not be handled either because a network component is not started or the specified resource name is not recognized.
ERROR_BAD_DEVICE | lpLocalName is invalid.
ERROR_BAD_NET_NAME | lpRemoteName was not recognized by any network.
ERROR_INVALID_PARAMETER | Either lpNetConnectInfoStruct does not point to a NETCONNECTINFOSTRUCT structure in which cbStructure is filled with the structure size, or both lpLocalName and lpRemoteName are not specified.
ERROR_NO_NETWORK | Network components are not running.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call WNetGetLastError.

Remarks

The information returned by the MultinetGetConnectionPerformance function is an estimate only. Network traffic and routing can affect the accuracy of the results returned.

A typical way to use this function would be to open a file on a network server (which would ensure that there is a connection to the file), call this function, and use the results to make decisions about how to manage file I/O. For example, you can decide whether to read the entire file into a temporary file on the client or directly access the file on the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NETRESOURCE, WNetGetLastError


NetAccessAdd

The NetAccessAdd function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessCheck

The NetAccessCheck function is obsolete. Win32-based applications should use the AccessCheck function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in svrapi.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessDel

The NetAccessDel function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessEnum

The NetAccessEnum function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessGetInfo

The NetAccessGetInfo function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessGetUserPerms

The NetAccessGetUserPerms function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAccessSetInfo

The NetAccessSetInfo functions is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetAlertRaise

The NetAlertRaise function notifies all registered clients that a particular event occurred.

Security Requirements

No special group membership is required to successfully execute NetAlertRaise.

NET_API_STATUS NetAlertRaise(
  LPWSTR AlertEventName,
  LPVOID Buffer,
  DWORD BufferSize
);

Parameters

AlertEventName
Pointer to a Unicode string that specifies the interrupting message to raise.
Buffer
Pointer to the data to be sent to the clients listening for this interrupting message. The data should consist of the STD_ALERT structure followed by any additional interrupting message data from the ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, and USER_OTHER_INFO data structures.
BufferSize
Specifies in bytes, the size of the buffer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetAlertRaiseEx


NetAlertRaiseEx

The NetAlertRaiseEx function simplifies the raising of an Administrators interrupting message.

Security Requirements

No special group membership is required to successfully execute NetAlertRaiseEx.

NET_API_STATUS NetAlertRaiseEx(
  LPWSTR AlertEventName,
  LPVOID VariableInfo,
  DWORD VariableInfoSize,
  LPWSTR ServiceName
);

Parameters

AlertEventName
Pointer to a Unicode string that specifies which type of interrupting message to raise.
VariableInfo
Information to put into the Administrators interrupting message.
VariableInfoSize
Number of bytes of variable information.
ServiceName
Name of the service raising the Administrators interrupting message.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetAlertRaiseEx


NetApiBufferAllocate

The NetApiBufferAllocate function allocates memory from the heap. Use this function only when compatibility with the NetApiBufferFree function is required. Otherwise, use LocalAlloc.

NET_API_STATUS NetApiBufferAllocate(
  DWORD ByteCount,
  LPVOID *Buffer
);

Parameters

ByteCount
The number of bytes to allocate.
buffer
Pointer to the location at which to store the pointer to the allocated buffer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferReallocate


NetApiBufferFree

The NetApiBufferFree function frees the memory that NetApiBufferAllocate allocates. Use this function to free the memory that other Net functions return.

NET_API_STATUS NetApiBufferFree(
  LPVOID Buffer
);

Parameters

Buffer
Pointer to an information buffer that other Net functions previously returned on a function call.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferAllocate , NetApiBufferReallocate


NetApiBufferReallocate

The NetApiBufferReallocate function changes the size of a buffer allocated with NetApiBufferAllocate.

NET_API_STATUS NetApiBufferReallocate(
  LPVOID OldBuffer,
  DWORD NewByteCount,
  LPVOID NewBuffer
);

Parameters

OldBuffer
Pointer to the reallocated buffer.
NewByteCount
The new size of the buffer.
NewBuffer
Pointer to a function information buffer previously returned on a function call.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferAllocate


NetApiBufferSize

The NetApiBufferSize function returns the size, in bytes, of the allocated buffer using NetApiBufferAllocate.

NET_API_STATUS NetApiBufferSize(
  LPVOID buffer,
  DWORD ByteCount
);

Parameters

buffer
Pointer to a function information buffer previously returned on a function call.
ByteCount
The size of the buffer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferFree


NetAuditClear

The NetAuditClear function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetAuditRead

The NetAuditRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmapibuf.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetConfigGet

The NetConfigGet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmconfig.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetConfigGetAll

The NetConfigGetAll function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmconfig.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetConfigSet

The NetConfigSet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmconfig.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetConnectionEnum

The NetConnectionEnum function lists all connections made to a shared resource on the server or all connections established from a particular computer. If there is more than one user using this connection, then it is possible to get more than one structure for the same connection, but with a different user name. The NetConnectionEnum function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

Security Requirements

Admin or server, print, or comm operator group membership is required to successfully execute NetConnectionEnum.

NET_API_STATUS NetConnectionEnum(
  LPWSTR servername,
  LPWSTR qualifier,
  DWORD level,
  LPTBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle,
);

Parameters

servername
A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
qualifier
A pointer to a Unicode string containing a share name or computer name for the connections of interest. If it is a share name, then all the connections made to that share name are listed. If it is a computer name (for example, it starts with two backslash characters), then NetConnectionEnum lists all connections made from that computer to the server specified.
level
Level of information required. 0 and 1 are valid.
bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen
Prefered maximum length of returned data (in 8-bit bytes).
entriesread
On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries
On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
Resume_handle
On return, a resume_handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing connection search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetDfsAdd

The NetDfsAdd function creates a new junction point or adds shares to an existing junction point in a Distributed File System (Dfs) tree structure.

NET_API_STATUS NET_API_FUNCTION NetDfsAdd(
  LPWSTR DfsEntryPath,   // Dfs entry path for the added junction
                         // point
  LPWSTR ServerName,     // name of server exporting the storage
  LPWSTR ShareName,      // existing share name for the storage
  LPWSTR Comment,        // optional comment for the junction point
  DWORD Flags            // zero for no flags
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string must be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references.
Comment
[in] Pointer to a null-terminated Unicode character string that contains an optional comment associated with the junction point.
Flags
[in] Specifies a flag value. If you set this parameter to the value DFS_ADD_VOLUME, the NetDfsAdd function will fail if the junction point already exists. If you set this parameter to zero, the function either creates a new junction point if one does not exist, or it adds a new share to an existing junction point.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetDfsEnum, NetDfsRemove


NetDfsEnum

The NetDfsEnum function enumerates all the junction points in the named Distributed File System (Dfs) tree structure. The function returns information about the junction points based on information specified by the Level parameter.

NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
  LPWSTR DfsName,        // name of the Dfs for enumeration
  DWORD Level,           // level of information requested
  DWORD PrefMaxLen,      // advisory, but -1 means return all
                         // information
  LPBYTE *Buffer,        // function allocates and returns buffer
                         // with requested info
  LPDWORD EntriesRead,   // number of entries returned
  LPDWORD ResumeHandle   // must be 0 on first call, reused on
                         // subsequent calls
);

Parameters

DfsName
[in] Pointer to a null-terminated Unicode character string that specifies the name of a Windows NT server that hosts the Dfs root volume.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
1 | Return Dfs junction point names. The Buffer parameter will contain an array of DFS_INFO_1 structures.
2 | Return Dfs junction point names with information. The Buffer parameter will contain an array of DFS_INFO_2 structures.
3 | Return Dfs junction point names with information, and share information. The Buffer parameter will contain an array of DFS_INFO_3 structures.

PrefMaxLen
[in] Specifies the preferred maximum number of bytes that should be returned by this enumeration function call in the information structure buffer. If you specify the value – 1, the NetDfsEnum function determines the number of bytes to return based on the information available. For additional information, see the following Remarks section.
Buffer
[out] Pointer to the address of a buffer that contains the requested information structures.
EntriesRead
[out] Pointer to a DWORD value that contains the actual enumerated junction point count.
ResumeHandle
[in/out] Pointer to a DWORD value that contains a handle that is used to continue the enumeration. The handle should be zero on the first call and left unchanged for subsequent calls.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Call the NetDfsEnum function with the ResumeHandle parameter set to zero to begin the enumeration. To retrieve information about additional junction points, call the function with the ResumeHandle returned by the previous call to NetDfsEnum.

The NetDfsEnum function allocates the memory required for the information structure buffer. If you specify an amount in the PrefMaxLen parameter, it restricts the number of bytes that the function returns. However, the actual size of the memory that the NetDfsEnum function allocates can be greater than the amount you specify. For additional information see Enumeration Buffer Lengths.

You can use the PrefMaxLen value for performance tuning. For example, if you call the function to fill a list box, and the list box can hold only 10 entries, a reasonable value for PrefMaxLen might be 12 * sizeof(DFS_INFO_n).

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_STORAGE_INFO, NetDfsAdd, NetDfsRemove


NetDfsGetInfo

The NetDfsGetInfo function retrieves information about a junction point in the named Distributed File System (Dfs) tree structure. The function can return information specific to a server and share, or information specific to an entire junction point.

NET_API_STATUS NET_API_FUNCTION NetDfsGetInfo(
  LPWSTR DfsEntryPath,        // Dfs entry path for the junction point
  LPWSTR ServerName OPTIONAL, // name of server exporting the storage
  LPWSTR ShareName OPTIONAL,  // name of share exporting the storage
  DWORD Level,                // level of information requested
  LPBYTE* Buffer              // function allocates and returns
                              // buffer with requested info
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string must be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path name on the physical share.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. This parameter is optional. For additional information, see the following Remarks section.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. This parameter is optional. For additional information, see the following Remarks section.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
1 | Return the Dfs junction point name. The Buffer parameter will contain a DFS_INFO_1 structure.
2 | Return the Dfs junction point name with information. The Buffer parameter will contain a DFS_INFO_2 structure.
3 | Return the Dfs junction point name with information, and share information. The Buffer parameter will contain a DFS_INFO_3 structure.
100 | Return a comment about the Dfs junction point. The Buffer parameter will contain a DFS_INFO_100 structure.

Buffer
[out] Pointer to the address of a buffer that contains the requested information structures.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The NetDfsGetInfo function allocates the memory required for the information structure buffer.

If you specify both the ServerName and ShareName parameters, the NetDfsGetInfo function returns information specific to that server and share. If the parameters are not specified, the function returns information that is specific to the entire junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_INFO_100, DFS_STORAGE_INFO, NetDfsEnum


NetDfsRemove

The NetDfsRemove function removes a server share from a junction point in a Distributed File System (Dfs) tree structure. If the specified share is the last share associated with the junction point, then the NetDfsRemove function also removes the junction point.

NET_API_STATUS NET_API_FUNCTION NetDfsRemove(
  LPWSTR DfsEntryPath,   // Dfs entry path for the junction point
  LPWSTR ServerName,     // name of server exporting the storage
  LPWSTR ShareName       // name of share exporting the storage
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string must be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetDfsAdd, NetDfsEnum


NetDfsSetInfo

The NetDfsSetInfo function associates information with a junction point in the named Distributed File System (Dfs) tree structure. The function can set information relevant to a specific server and share, or information specific to an entire junction point.

NET_API_STATUS NET_API_FUNCTION NetDfsSetInfo(
  LPWSTR DfsEntryPath,        // Dfs entry path for the junction point
  LPWSTR ServerName OPTIONAL, // name of server exporting the storage
  LPWSTR ShareName OPTIONAL,  // name of share exporting the storage
  DWORD Level,                // level of information to be set
  LPBYTE Buffer               // buffer holding information
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string must be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. This parameter is optional. For additional information, see the following Remarks section.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. This parameter is optional. For additional information, see the following Remarks section.
Level
[in] Specifies the information level of the set request. This parameter must be the following value.
Value | Meaning
100 | Return a comment about the Dfs junction point. The Buffer parameter contains a DFS_INFO_100 structure.

Buffer
[in] Pointer to a buffer that contains the information structure.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

If you specify both the ServerName and ShareName parameters, the NetDfsSetInfo function returns information specific to that server and share. If the parameters are not specified, the function returns information that is specific to the entire junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, DFS_INFO_100, NetDfsEnum


NetErrorLogClear

The NetErrorLogClear function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmerrlog.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetErrorLogRead

The NetErrorLogRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmerrlog.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetFileClose

The NetFileClose function is obsolete in the Win32-based application programming interface (API). It is included for compatibility with 16-bit versions of Windows.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetFileEnum

The NetFileEnum function supplies information about some or all open files on a server, allowing the user to supply a resume handle and get required information through repeated calls to the function.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetFileEnum.

NET_API_STATUS NetFileEnum(
  LPWSTR servername,
  LPWSTR basepath,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
basepath
Pointer to a Unicode string containing a qualifier for the returned information. If NULL, all open resources are enumerated. If not NULL, the function enumerates only resources that have basepath as a prefix. A prefix is the path component up to a backslash.
username
Pointer to a Unicode string that specifies the name of the user. If not NULL, username serves as a qualifier for the enumeration. The files returned are limited to those that have user names matching the qualifier. If username is NULL, no user-name qualifier is used.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
2 | Return file identification number. The returned buffer will contain an array of FILE_INFO_2 structures.
3 | Return information about the file. The returned buffer will contain an array of FILE_INFO_3 structures.

bufptr
Pointer to the address of the return information structure.
prefmaxlen
Preferred maximum length, in 8-bit bytes, of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resume_handle
Pointer to a DWORD that contains a resume handle, which is used to continue an existing file search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetFileGetInfo


NetFileGetInfo

The NetFileGetInfo function retrieves information about a particular opening of a server resource.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetFileGetInfo.

NET_API_STATUS NetFileGetInfo(
  LPWSTR servername,
  DWORD fileid,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
fileid
File identifier of the open resource for which to return information. The fileid value must be that returned in a previous enumeration call.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
2 | Return file identification number. Points to a buffer that contains an array of FILE_INFO_2 structures.
3 | Return information about the file. Points to a buffer that contains an array of FILE_INFO_3 structures.

bufptr
Pointer to the address of the return information structure.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_FILE_NOT_FOUND | The file was not found.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available
NERR_BufTooSmall | The supplied buffer is too small.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetFileEnum


NetGetAnyDCName

The NetGetAnyDCName function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. For NT5 and subsequent versions, Win32-based applications should use the DSGetDCName function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGetDCName


NetGetDCName

The NetGetDCName function returns the name of the Primary Domain Controller (PDC). It does not return the name of the Backup Domain Controller (BDC) for the specified domain. Also, you cannot remote this function to a non-PDC server.

The NetGetDCName function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. For NT5 and subsequent versions, Win32-based applications should use the DSGetDCName function.

Security Requirements

No special group membership is required to successfully execute NetGetDCName.

NET_API_STATUS NetGetDCName(
  LPWSTR servername,
  LPWSTR domainname,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
domainname
Pointer to a Unicode string containing the name of the domain. A NULL pointer or string indicates that the function returns the name of the domain controller for the primary domain.
bufptr
Returns a pointer to an allocated buffer containing a Unicode string which identifies the server name of the PDC of the domain. The server name is prefixed by \\. The buffer should be deallocated using NetApiBufferFree.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
NERR_DCNotFound | Could not find the domain controller for the domain.
ERROR_INVALID_NAME | The name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGetAnyDCName


NetGetDisplayInformationIndex

The NetGetDisplayInformationIndex function gets the index of the first display information entry whose name begins with a specified string or alphabetically follows the string. You can use this function to determine a starting index for subsequent calls to the NetQueryDisplayInformation function.

Security Requirements

No special group membership is required to successfully execute NetGetDisplayInformationIndex.

NET_API_STATUS NetGetDisplayInformationIndex(
  LPWSTR ServerName,  // pointer to server to get information from
  DWORD Level,        // level of information to retrieve
  LPWSTR Prefix,      // pointer to prefix string
  LPDWORD Index       // receives index of entry
);

Parameters

ServerName
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
Level
Specifies one of the following values to return the level of information provided.
Value | Meaning
1 | Query all Local and Global (normal) user accounts.
2 | Query all Workstation and Server user accounts.
3 | Query all Global Groups.

Prefix
Pointer to a null-terminated Unicode string containing the prefix for which to search.
Index
Pointer to a 32-bit variable that receives the index of the entry.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NO_MORE_ITEMS | There were no more items on which to operate.
NERR_InvalidComputer | The computer name is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetQueryDisplayInformation


NetGroupAdd

The NetGroupAdd function creates a global group in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupAdd.

NET_API_STATUS NetGroupAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information pointed to in the buf parameter.
Value | Meaning
0 | Specify group name. The buf parameter contains a pointer to a GROUP_INFO_0 structure.
1 | Specify group name and a comment. The buf parameter contains a pointer to a GROUP_INFO_1 structure.
2 | Specifies information about the group. The buf parameter contains a pointer to a GROUP_INFO_2 structure.

buf
Pointer to a buffer containing the global group information structure.
parm_err
Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL, the parameter is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupExists | The group already exists.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupAddUser, NetGroupDel


NetGroupAddUser

The NetGroupAddUser function gives an existing user account membership in an existing global group.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupAddUser.

NET_API_STATUS NetGroupAddUser(
  LPWSTR servername,
  LPWSTR GroupName,
  LPWSTR username
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
GroupName
Pointer to a Unicode string containing the name of the global group to which the user is to be given membership.
Username
Pointer to a Unicode string containing the name of the user to be given global group membership.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.
NERR_GroupExists | The group already exists.
NERR_UserNotFound | The user name could not be found.
NERR_GroupNotFound | The group name could not be found.
NERR_UserNotInGroup | The user does not belong to this group.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupAdd, NetGroupAddUser, NetGroupDel, NetGroupDelUser


NetGroupDel

The NetGroupDel function deletes a global group account from the account database.

Security Requirements

Only members of the Administrators or the Account Operators local group can successfully execute NetGroupDel.

NET_API_STATUS NetGroupDel(
  LPWSTR servername,
  LPWSTR groupname
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
groupname
Pointer to a Unicode string containing the name of the global group account to delete.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.
NERR_GroupNotFound | The group name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupAdd


NetGroupDelUser

The NetGroupDelUser function removes a user from a particular global group in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupDelUser.

NET_API_STATUS NetGroupDelUser(
  LPWSTR servername,
  LPWSTR GroupName,
  LPWSTR Username
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
GroupName
Pointer to a Unicode string containing the name of the global group from which the user membership is to be removed.
Username
Pointer to a Unicode string containing the name of the user to remove from the global group.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups..
NERR_UserNotFound | The user name could not be found.
NERR_GroupNotFound | The group name could not be found.
NERR_UserNotInGroup | The user does not belong to this group.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupAddUser


NetGroupEnum

The NetGroupEnum function retrieves information about each global group account.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupEnum.

NET_API_STATUS NetGroupEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
0 | Return group name. The returned buffer points to an array of GROUP_INFO_0 structures.
1 | Return group name and comment. The returned buffer points to an array of GROUP_INFO_1 structures.
2 | Return information about the group. The returned buffer points to an array of GROUP_INFO_2 structures.

bufptr
Pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using NetApiBufferFree.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resume_handle
Pointer to a DWORD that contains a resume_handle, which is used to continue an existing global group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Remarks

The NetQueryDisplayInformation function provides a very efficient mechanism for enumerating global group accounts. When possible, use that function instead of NetGroupEnum.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetQueryDisplayInformation, NetGroupGetInfo


NetGroupGetInfo

The NetGroupGetInfo function retrieves information about a particular global group account on a server.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupGetInfo.

NET_API_STATUS NetGroupGetInfo(
  LPWSTR servername,
  LPWSTR groupname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
groupname
Pointer to a Unicode string containing the name of the global group account on which to return information.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
0 | Return group name. The returned buffer points to an array of GROUP_INFO_0 structures.
1 | Return group name and comment. The returned buffer points to an array of GROUP_INFO_1 structures.
2 | Return information about the group. The returned buffer points to an array of GROUP_INFO_2 structures.

bufptr
Pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using NetApiBufferFree.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupNotFound | The group name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupSetInfo


NetGroupGetUsers

The NetGroupGetUsers function retrieves a list of the members of a particular global group in the security database.

NET_API_STATUS NetGroupGetUsers(
  LPWSTR servername,
  LPWSTR groupname,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumeHandle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
groupname
Pointer to a Unicode string containing the name of the global group whose members are to be listed.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
0 | Return the group name. The returned buffer points to an array of GROUP_USERS_INFO_0 structures.
1 | Return the group attributes. The returned buffer points to an array of GROUP_USERS_INFO_1 structures.

bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using NetApiBufferFree.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumeHandle
Pointer to a DWORD that contains resumeHandle, which is used to continue an existing user group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumeHandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupNotFound | The group name could not be found.
ERROR_MORE_DATA | More entries are available with subsequent calls.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupSetUsers


NetGroupSetInfo

The NetGroupSetInfo function sets the parameters of a global group account.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupSetInfo.

NET_API_STATUS NetGroupSetInfo(
  LPWSTR servername,
  LPWSTR groupname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
groupname
Pointer to a Unicode string containing the name of the global group account to set information on.
level
Specifies one of the following values to set the level of information pointed to in the buf parameter.
Value | Meaning
0 | Specify group name. The specified buffer points to an array of GROUP_INFO_0 structures.
1 | Specifiy group name and comment. The specified buffer points to an array of GROUP_INFO_1 structures.
2 | Specify information about the group. The specified buffer points to an array of GROUP_INFO_2 structures.
1002 | Specify comments about the group. The specified buffer points to an array of GROUP_INFO_1002 structures.
1005 | Specify group attributes. The specified buffer points to an array of GROUP_INFO_1005 structures.

buf
Pointer to a buffer containing the global group information.
parm_err
Optional pointer to a DWORD that returns the index of the first parameter in error following an ERROR_INVALID_PARAMETER message. If NULL the parameter is not returned on error.

Remarks

You can call NetGroupSetInfo with GROUP_INFO_1 and specify a value using the grpi1_name member. However, that value will be ignored. The correct way to specify the new name of the group is to call NetGroupSetInfo with GROUP_INFO_0 and specify a value using grpi0_name.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The group name could not be found.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupGetInfo


NetGroupSetUsers

The NetGroupSetUsers function sets the global group membership for the specified global group. Each user specified is made a member of the global group. Users that are not specified but are currently members of the global group will have their membership revoked.

One use of NetGroupSetUsers is to replace the current membership with an entirely new membership. The typical sequence is to use the NetGroupGetUsers function, modify the returned membership list to look the way you want it to be, then call NetGroupSetUsers.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupSetUsers on a remote server.

NET_API_STATUS NetGroupSetUsers(
  LPWSTR servername,
  LPWSTR groupname,
  DWORD level,
  LPBYTE buf,
  DWORD NewMemberCount
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
groupname
Pointer to a Unicode string containing the name of the global group to which the specified users belong.
level
Specifies one of the following values to set the level of information pointed to in the buf parameter.
Value | Meaning
0 | Specify group name. The specified buffer points to an array of GROUP_USERS_INFO_0 structures.
1 | Specify group attributes. The specified buffer points to an array of GROUP_USERS_INFO_1 structures.

buf
Pointer to the buffer location of the designated data.
NewMemberCount
Specifies the number of entries in the buffer pointed to by buf.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The group name could not be found.
NERR_UserNotFound | The user name could not be found.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetGroupAddUser, NetGroupDel, NetGroupDelUser


NetHandleGetInfo

The NetHandleGetInfo function retrieves handle-specific information for character-device and named-pipe handles.

Security Requirements

Access restrictions to the named pipe or character device also determine access privileges to NetHandleGetInfo.

NET_API_STATUS NetHandleGetInfo(
  UNSIGNED SHORT hHandle,
  SHORT sLevel,
  CHAR FAR *pbBuffer,
  UNSIGNED SHORT cbBuffer,
  UNSIGNED SHORT FAR *pcbTotalAvail
);

Parameters

hHandle
Identifies a communication-device queue or a named pipe.
sLevel
Specifies the level of detail (1 or 2) requested.

Note The NetHandleGetInfo function can be called at level 1 only if the value of the hHandle parameter is a valid handle to a named pipe or character device that exists on a remote server.

The NetHandleGetInfo function can be called at level 2 only if the value of the hHandle parameter is a handle to the server side of a valid named pipe opened on a remote computer. If the named pipe has been opened locally or if the handle is not for a named pipe, NetHandleGetInfo returns ERROR_INVALID_PARAMETER.

pbBuffer
Pointer to the buffer in which to store the returned data. If the function returns successfully, the buffer contains a handle_info_1 structure.
cbBuffer
Specifies the size, in bytes, of the data buffer pointed to by the pbBuffer parameter.
pcbTotalAvail
Pointer to an unsigned short integer in which the total number of bytes of information available is returned. This count is valid only if NetHandleGetInfo returns nerr_success, error_more_data, or nerr_buftoosmall.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmchdev.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, HANDLE_INFO_1, NetHandleSetInfo


NetHandleSetInfo

The NetHandleSetInfo function sets handle-specific information for character-device and named-pipe handles.

Security Requirements

Access restrictions to the character device or named pipe determines access privilege.

NET_API_STATUS NetHandleSetInfo(
  UNSIGNED SHORT hHandle,
  SHORT sLevel,
  CHAR FAR *pbBuffer,
  UNSIGNED SHORT cbBuffer,
  UNSIGNED SHORT FAR *sParmNum
);

Parameters

hHandle
Identifies a communication-device queue or a named pipe.
sLevel
Specifies the level of detail provided; must be 1.
pbBuffer
Pointer to the data to be set.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.
sParmNum
Specifies whether to reset all handle information or to change only a part of it. If the value of sParmNum is PARMNUM_ALL, the pbBuffer parameter must point to the handle_info_1 structure, and the previous handle information is replaced by this new information. If sParmNum is any other defined value, only one element of the handle information is changed, and the pbBuffer parameter must point to a valid value for that element.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmchdev.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, HANDLE_INFO_1, NetHandleSetInfo


NetLocalGroupAdd

The NetLocalGroupAdd function creates a local group in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupAdd.

NET_API_STATUS NetLocalGroupAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information pointed to in the buf parameter.
Value | Meaning
0 | Specify local group name of the user. The specified buffer points to an array of LOCALGROUP_INFO_0 structures.
1 | Specify local group attributes of the user. The specified buffer points to an array of LOCALGROUP_INFO_1 structures.

buf
Pointer to a buffer containing the local group information structure.
parm_err
Optional pointer to a DWORD that returns the index of the first parameter to cause ERROR_INVALID_PARAMETER. If NULL the parameter is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupExists | The group already exists.
NERR_UserExists | The user account already exists.
ERROR_ALIAS_EXISTS | An error occurs when accessing the alias.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupDel


NetLocalGroupAddMember

The NetLocalGroupAddMember function is obsolete. Win32-based applications should use the NetLocalGroupAddMembers function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetLocalGroupAddMembers

The NetLocalGroupAddMembers function adds membership of one or more existing user accounts or global groups to an existing local group. The function does not change the membership status of users or global groups that are currently members of the local group.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupAddMembers on a remote server.

NET_API_STATUS NetLocalGroupAddMembers(
  LPWSTR servername,
  LPWSTR LocalGroupName,
  DWORD level,
  LPBYTE buf,
  DWORD membercount
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a null-terminated Unicode string containing the name of the local group to which the specified users or global groups will be added.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
Pointer to a buffer containing the data for the new members.
membercount
Specifies the number of entries in the buffer pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
ERROR_NO_SUCH_MEMBER | One or more of the new members do not exist. Therefore, no new members were added.
ERROR_MEMBER_IN_ALIAS | One or more of the members specified were already members of the local group. Therefore, no new members were added.
ERROR_INVALID_MEMBER | One or more of the members cannot be added because their account type is invalid. Therefore, no new members were added.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupAdd, NetLocalGroupDelMembers, NetLocalGroupGetMembers


NetLocalGroupDel

The NetLocalGroupDel function deletes a local group account and all its members from the accounts database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupDel.

NET_API_STATUS NetLocalGroupDel(
  LPWSTR servername,
  LPWSTR LocalGroupName
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a Unicode string containing the name of the local group account to delete.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupExists | The group already exists.
NERR_UserExists | The user account already exists.
ERROR_NO_SUCH_ALIAS | The alias group does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupAdd


NetLocalGroupDelMember

The NetLocalGroupDelMember function is obsolete. Win32-based applications should use the NetLocalGroupDelMembers function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetLocalGroupDelMembers

The NetLocalGroupDelMembers function removes one or more members from an existing local group.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupDelMembers on a remote server.

NET_API_STATUS NetLocalGroupDelMembers(
  LPWSTR servername,
  LPWSTR LocalGroupName,
  DWORD level,
  LPBYTE buf,
  DWORD membercount
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a null-terminated Unicode string containing the name of the local group from which the specified users or global groups will be removed.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
Pointer to the buffer containing data that describes the removed members.
membercount
Specifies the number of entries in the array pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
ERROR_NO_SUCH_MEMBER | One or more of the members do not exist. Therefore, no members were deleted.
ERROR_MEMBER_IN_ALIAS | One or more of the members specified were not members of the local group. Therefore, no members were deleted.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupAddMembers, NetLocalGroupDel, NetLocalGroupGetMembers


NetLocalGroupEnum

The NetLocalGroupEnum function retrieves information about each local group account.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupEnum.

NET_API_STATUS NetLocalGroupEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
0 | Return the local group name of the user. The returned buffer points to an array of LOCALGROUP_INFO_0 structures.
1 | Return local group attributes of the user. The returned buffer points to an array of LOCALGROUP_INFO_1 structures.

bufptr
On return, a pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using the NetApiBufferFree function.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumehandle
Pointer to a DWORD that contains a resumehandle, which is used to continue an existing local group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetQueryDisplayInformation, NetLocalGroupGetInfo


NetLocalGroupGetInfo

The NetLocalGroupGetInfo function retrieves information about a particular local group account on a server.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupGetInfo.

NET_API_STATUS NetLocalGroupGetInfo(
  LPWSTR servername,
  LPWSTR LocalGroupName,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a Unicode string containing the name of the local group account on which to return information.
level
Specifies one of the following values to return the level of information pointed to in the bufptr parameter.
Value | Meaning
0 | Return the local group name of the user. The returned buffer points to an array of LOCALGROUP_INFO_0 structures.
1 | Return local group attributes of the user. The returned buffer points to an array of LOCALGROUP_INFO_1 structures.

bufptr
Pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_NO_SUCH_ALIAS | The alias group does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetQueryDisplayInformation, NetLocalGroupSetInfo


NetLocalGroupGetMembers

The NetLocalGroupGetMembers function retrieves a list of the members of a particular local group in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupGetMembers. However, when the request is made by a user who has membership in the specified local group, in no special group membership is required.

NET_API_STATUS NetLocalGroupGetMembers(
  LPWSTR servername,
  LPWSTR localgroupname,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
localgroupname
Pointer to a Unicode string containing the name of the local group whose members are to be listed.
level
Specifies one of the following values to return the levels of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
1 | The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_1 structures.
2 | The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_2 structures.
3 | The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

bufptr
On return, a pointer to the return information structure is returned in the address pointed to by bufptr. The returned buffer should be deallocated using the NetApiBufferFree function.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumehandle
Pointer to a DWORD that contains resumehandle, which is used to continue an existing user group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_NO_SUCH_ALIAS | The alias group does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferFree, NetLocalGroupSetMembers


NetLocalGroupSetInfo

The NetLocalGroupSetInfo function sets the parameters of a local group.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupSetInfo.

NET_API_STATUS NetLocalGroupSetInfo(
  LPWSTR servername,
  LPWSTR LocalGroupName,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a Unicode string containing the name of the local group account on which to set information.
level
Specifies one of the following values to set the level of information pointed to in the buf parameter.
Value | Meaning
0 | Specify the local group name of the user. The buf parameter points to an array of LOCALGROUP_INFO_0 structures.
1 | Specify local group attributes of the user. The buf parameter points to an array of LOCALGROUP_INFO_1 structures.
1002 | Specify local group attributes of the user. The buf parameter points to an array of LOCALGROUP_INFO_1002 structures.

buf
Pointer to a buffer containing the local group information.
parm_err
Optional pointer to a DWORD to return the index of the first parameter that caused ERROR_INVALID_PARAMETER. If NULL the parameter is not returned on error.

Remarks

You can call NetLocalGroupSetInfo with LOCALGROUP_INFO_1 and specify a value using the lgrpi1_name member. However, that value will be ignored. The correct way to specify the new name of the group is to call NetLocalGroupSetInfo with LOCALGROUP_INFO_0 and specify a value using the lgrpi0_name member.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_InvalidComputer | The computer name is invalid.
ERROR_NO_SUCH_ALIAS | The alias group does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupGetInfo


NetLocalGroupSetMembers

The NetLocalGroupSetMembers function sets the local group membership for the specified local group. Each user or global group specified is made a member of the local group. Users or global groups that are not specified but are currently members of the local group will have their membership revoked.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetLocalGroupSetMembers on a remote server.

NET_API_STATUS NetLocalGroupSetMembers(
  LPWSTR servername,
  LPWSTR LocalGroupName,
  DWORD level,
  LPBYTE buf,
  DWORD totalentries
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
LocalGroupName
Pointer to a Unicode string containing the name of the local group to which the specified users or global groups belong.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
Pointer to the buffer in which the data to be set is stored.
totalentries
Specifies the total number of entries in the buffer that the buf parameter points to.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
NERR_GroupNotFound | The specified LocalGroupName does not exist.
ERROR_NO_SUCH_MEMBER | One or more of the members doesn't exist. Therefore, the local group membership was not changed.
ERROR_INVALID_MEMBER | One or more of the members cannot be added because it has an invalid account type. Therefore, the local group membership was not changed.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetLocalGroupGetMembers


NetMessageBufferSend

The NetMessageBufferSend function sends a buffer of information to a registered message alias.

Security Requirements

No special group membership is required to execute NetMessageBufferSend on a LAN Manager or Windows NT system. Admin, Accounts, Print, or Server operator group membership is required to successfully execute NetMessageBufferSend on a remote server.

NET_API_STATUS NetMessageBufferSend(
  LPWSTR servername,
  LPWSTR msgname,
  LPWSTR fromname,
  LPBYTE buf,
  DWORD buflen
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
msgname
Pointer to a Unicode string containing the message name to which the message buffer should be sent.
fromname
Pointer to a Unicode string containing the message name sending the information. The fromname parameter is new for Win32 networking. This parameter is needed for sending interrupting messages from the computer name rather than the logged on user. If NULL is specified, the message is sent from the logged-on user as with LAN Manager 2.x.
buf
Pointer to a buffer of message text.
buflen
The length, in bytes, of the message text in buf.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_SUPPORTED | This network request is not supported.
NERR_NameNotFound | The user name could not be found.
NERR_NetworkError | A general failure occurred in the network hardware.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetMessageNameAdd, NetMessageNameDel, NetMessageNameEnum, NetMessageNameGetInfo


NetMessageNameAdd

The NetMessageNameAdd function registers a message alias in the message name table. This function requires that the Messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetMessageNameAdd on a remote server.

NET_API_STATUS NetMessageNameAdd(
  LPWSTR servername,
  LPWSTR msgname
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
msgname
Pointer to a Unicode string containing the message name to be added. The string cannot be more than 15 characters long.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
NERR_AlreadyExists | The message alias already exists on this computer.
NERR_DuplicateName | The name specified is already in use as a message alias on the network.
NERR_NetworkError | A general failure occurred in the network hardware.
NERR_TooManyNames | The maximum number of message aliases has been exceeded.

Remarks

The forward action flag from the LAN Manager 2.x NetMessageNameAdd function is no longer a parameter because message forwarding is no longer supported. If the NetMessageNameAdd function detects that a forwarded version of msgname exists on the network, the function will fail with error NERR_Already_Exists.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetMessageNameDel


NetMessageNameDel

The NetMessageNameDel function deletes a message alias from the table of message aliases on a computer. This function requires that the Messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetMessageNameDel on a remote server.

NET_API_STATUS NetMessageNameDel(
  LPWSTR servername,
  LPWSTR msgname
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
msgname
Pointer to a Unicode string containing the message name to be deleted. The string cannot be more than 15 characters long.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_DelComputerName | A message alias that is also a computer name cannot be deleted.
NERR_IncompleteDel | The message alias was not successfully deleted from all networks.
NERR_NameInUse | The message alias is currently in use. Try again later.
NERR_NotLocalName | The message alias is not on the local computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetMessageNameAdd


NetMessageNameEnum

The NetMessageNameEnum function lists the message aliases that will receive messages on a specified computer. This function requires that the Messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetMessageNameEnum on a remote server.

NET_API_STATUS NetMessageNameEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the requested level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of MSG_INFO_0 structures.
1 | The bufptr parameter points to an array of MSG_INFO_1 structures.

bufptr
Points to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resume_handle
Pointer to a DWORD that contains resume_handle, which is used to continue an existing message name search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, no resume handle is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetMessageNameGetInfo


NetMessageNameGetInfo

The NetMessageNameGetInfo function retrieves information about a particular message alias in the message name table. This function requires that the Messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetMessageNameGetInfo on a remote server.

NET_API_STATUS NetMessageNameGetInfo(
  LPWSTR servername,
  LPWSTR msgname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
msgname
Pointer to a Unicode string containing the message name on which to return information.
level
Specifies one of the following values to indicate the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of MSG_INFO_0 structures.
1 | The bufptr parameter points to an array of MSG_INFO_1 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NotLocalName | The message alias is not on the local computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetMessageNameEnum


NetQueryDisplayInformation

The NetQueryDisplayInformation function returns user, computer, or global group account information. Use this function to quickly enumerate account information for display in user interfaces.

Security Requirements

No special group membership is required to successfully execute NetQueryDisplayInformation.

NET_API_STATUS NetQueryDisplayInformation(
  LPWSTR ServerName,
  DWORD Level,
  DWORD Index,
  DWORD EntriesRequested,
  DWORD PreferredMaximumLength,
  LPDWORD ReturnedEntryCount,
  PVOID *SortedBuffer
);

Parameters

ServerName
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
Level
Specifies one of the following values to return the level of information provided.
Value | Meaning
1 | Return all Local and Global (normal) user accounts. The returned buffer points to an array of NET_DISPLAY_USER structures.
2 | Return all Workstation and Server (BDC) user accounts. The returned buffer points to an array of NET_DISPLAY_MACHINE structures.
3 | Return all Global Groups. The returned buffer points to an array of NET_DISPLAY_GROUP structures.

Index
Specifies the index of the first entry for which to retrieve information. Specify zero to retrieve account information beginning with the first display information entry. If a call to NetQueryDisplayInformation returns ERROR_MORE_DATA, you can set Index to the value returned in the next_index member of the last entry in SortedBuffer to get data for additional entries. To retrieve information for entries beginning with a specified prefix, set Index to the index returned by a call to the NetGetDisplayInformationIndex function.
EntriesRequested
Specifies the maximum number of entries for which to get information.
PreferredMaximumLength
Specifies the preferred maximum size, in 8-bit bytes, of the system-allocated buffer returned in the SortedBuffer parameter.
ReturnedEntryCount
Pointer to a 32-bit variable that receives the number of entries in the buffer returned in the SortedBuffer parameter. Zero indicates that there are no entries with an index as large as that specified. Entries may be returned when the function's return value is either NERR_Success or ERROR_MORE_DATA.
SortedBuffer
Points to a variable that receives a pointer to a system-allocated buffer containing a sorted list of the requested information. This buffer contains an array of NET_DISPLAY_USER, NET_DISPLAY_MACHINE or NET_DISPLAY_GROUP structures. Use NetApiBufferFree to deallocate the buffer.

Return Values

If the function returns account information, the return value is one of the following values.

Value | Meaning
NERR_Success | There are no more entries to be returned.
ERROR_MORE_DATA | More entries are available. That is, the last entry returned in the SortedBuffer parameter is not the last entry available. To get information for additional entries, call NetQueryDisplayInformation again with the Index parameter set to the value returned in the next_index member of the last entry in SortedBuffer.

If the function fails, the return value is one of the following error code.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The Level parameter specifies an invalid value.

Remarks

The NetQueryDisplayInformation and NetGetDisplayInformationIndex functions provide a very efficient mechanism for enumerating User and Global group accounts. When possible, use these functions instead of the NetUserEnum and NetGroupEnum functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NET_DISPLAY_USER, NetApiBufferFree, NetGetDisplayInformationIndex, NetGroupEnum, NetUserEnum


NetRemoteTOD

The NetRemoteTOD function returns the time of day information from a specified server.

Security Requirements

No special group membership is required to successfully execute NetRemoteTOD.

NET_API_STATUS NetRemoteTOD(
  LPWSTR UncServerName,
  LPBYTE *BufferPtr
);

Parameters

UncServerName
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
BufferPtr
On return a pointer to the return information structure TIME_OF_DAY_INFO is returned in the address pointed to by BufferPtr.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmremutl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetReplExportDirAdd

The NetReplExportDirAdd function registers an existing directory in the export path to be replicated.

Security Requirements

Only members of the Administrators local group or members of the Account Operators local group can successfully execute NetReplExportDirAdd.

NET_API_STATUS NetReplExportDirAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to set the level of information provided.
Value | Meaning
1 | The buf parameter points to an array of REPL_EDIR_INFO_1 structures.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL the parameter is not returned on error.

Remarks

The default values for locktime and lockcount are both 0.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirDel, REPL_EDIR_INFO_1


NetReplExportDirDel

The NetReplExportDirDel function removes registration of a replicated directory.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetReplExportDirDel.

NET_API_STATUS NetReplExportDirDel(
  LPWSTR servername,
  LPWSTR dirname
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the name of a replicated directory to remove from the registration files.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirAdd


NetReplExportDirEnum

The NetReplExportDirEnum function lists the replicated directories in the export path.

Security Requirements

No special group membership is required to successfully execute NetReplExportDirEnum.

NET_API_STATUS NetReplExportDirEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of REPL_EDIR_INFO_0 structures.
1 | The bufptr parameter points to an array of REPL_EDIR_INFO_1 structures.
2 | The bufptr parameter points to an array of REPL_EDIR_INFO_2 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data. A value of 0xFFFFFFFF indicates that all available entries should be returned.
entriesread
Pointer to a DWORD that contains the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle
Pointer to a DWORD that contains resumehandle, which is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirGetInfo


NetReplExportDirGetInfo

The NetReplExportDirGetInfo function retrieves the control information of a replicated directory.

Security Requirements

No special group membership is required to successfully execute NetReplExportDirGetInfo.

NET_API_STATUS NetReplExportDirGetInfo(
  LPWSTR servername,
  LPWSTR dirname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name about which to return control information.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of REPL_EDIR_INFO_0 structures.
1 | The bufptr parameter points to an array of REPL_EDIR_INFO_1 structures.
2 | The bufptr parameter points to an array of REPL_EDIR_INFO_2 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirSetInfo, NetReplExportDirEnum


NetReplExportDirLock

The NetReplExportDirLock function locks a replicated directory so that replication from it can be suspended. This function increments the lock reference count for the specified directory.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetReplExportDirLock.

NET_API_STATUS NetReplExportDirLock(
  LPWSTR servername,
  LPWSTR dirname
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name to lock.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirUnlock


NetReplExportDirSetInfo

The NetReplExportDirSetInfo function modifies the control information of a replicated directory.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetReplExportDirSetInfo.

NET_API_STATUS NetReplExportDirSetInfo(
  LPWSTR servername,
  LPWSTR dirname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name to return control information about.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
1 | The buf parameter points to an array of REPL_EDIR_INFO_1 structures.
1000 | The buf parameter points to an array of REPL_EDIR_INFO_1000 structures.
1001 | The buf parameter points to an array of REPL_EDIR_INFO_1001 structures.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the identifier of the first parameter error when the function sends an ERROR_INVALID_PARAMETER message. If NULL, the parameter is not returned on error.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirGetInfo


NetReplExportDirUnlock

The NetReplExportDirUnlock function unlocks a directory so that replication from it can resume. This function decrements the lock reference count for the specified directory.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetReplExportDirUnlock.

NET_API_STATUS NetReplExportDirUnlock(
  LPWSTR servername,
  LPWSTR dirname,
  DWORD unlockforce
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name to unlock.
unlockforce
Value that indicates the force level necessary to unlock the directory.

Force levels:

REPL_UNLOCK_NOFORCE
Unlocks the directory by decrementing the lock reference count. The lock reference count may or may not return to 0, so the directory could still be locked.
REPL_UNLOCK_FORCE
Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplExportDirLock


NetReplGetInfo

The NetReplGetInfo function retrieves configuration information for the Replicator service.

Security Requirements

No special group membership is required to successfully execute NetReplGetInfo.

NET_API_STATUS NetReplGetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of REPL_INFO_0 structures.

bufptr
Points to the buffer in which the data set with the level parameter is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplSetInfo


NetReplImportDirAdd

The NetReplImportDirAdd function registers an existing directory in the import path to receive replication from a master.

Security Requirements

Only members of the Administrators or Replicator group can successfully execute NetReplImportDirAdd.

NET_API_STATUS NetReplImportDirAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of REPL_IDIR_INFO_0 structures.

buf
Pointer to a buffer in which data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains an index to the first parameter that caused ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirDel


NetReplImportDirDel

The NetReplImportDirDel function removes the registration of a directory so that it no longer receives updates from the master. Note that this function does not actually delete the directory from the file system. The Replicator service can automatically register the directory service at any time. To prevent the importing of a directory that is being exported by some Replicator service, use the NetReplImportDirLock function instead.

Security Requirements

Only members of the Administrators local group or Replicator groups can successfully execute NetReplImportDirDel.

NET_API_STATUS NetReplImportDirDel(
  LPWSTR servername,
  LPWSTR dirname
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the name of a replicated directory to remove the registration.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirAdd


NetReplImportDirEnum

The NetReplImportDirEnum function lists the replicated directories in the import path.

Security Requirements

No special group membership is required to successfully execute NetReplImportDirEnum.

NET_API_STATUS NetReplImportDirEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of REPL_IDIR_INFO_0 structures.
1 | The bufptr parameter points to an array of REPL_IDIR_INFO_1 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data. A value of 0xFFFFFFFF indicates that all available entries should be returned.
entriesread
Pointer to a DWORD that contains the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle
Pointer to a DWORD that contains resumehandle, which is used to continue an existing search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirGetInfo, REPL_IDIR_INFO_0, REPL_IDIR_INFO_1


NetReplImportDirGetInfo

The NetReplImportDirGetInfo function retrieves the status information on a client replicated directory.

Security Requirements

No special group membership is required to successfully execute NetReplImportDirGetInfo.

NET_API_STATUS NetReplImportDirGetInfo(
  LPWSTR servername,
  LPWSTR dirname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name about which to return control information.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of REPL_IDIR_INFO_0 structures.
1 | The bufptr parameter points to an array of REPL_IDIR_INFO_1 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirEnum, REPL_IDIR_INFO_0, REPL_IDIR_INFO_1


NetReplImportDirLock

The NetReplImportDirLock function locks a replicated directory so that replication to it can be suspended. This function increments the lock reference count for the specified directory.

Security Requirements

Only the Administrators local group or replicator group membership is required to successfully execute NetReplImportDirLock.

NET_API_STATUS NetReplImportDirLock(
  LPWSTR servername,
  LPWSTR dirname
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name to lock.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirUnlock


NetReplImportDirUnlock

The NetReplImportDirUnlock function unlocks a directory so that replication to it can resume. This function decrements the lock reference count for the specified directory.

Security Requirements

Only the Administrators local group or replicator group membership is required to successfully execute NetReplImportDirUnlock.

NET_API_STATUS NetReplImportDirUnlock(
  LPWSTR servername,
  LPWSTR dirname,
  DWORD unlockforce
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
dirname
Pointer to a null-terminated Unicode string containing the directory name to unlock.
unlockforce
A value that indicates the force level necessary to unlock the directory.

Force levels:

REPL_UNLOCK_NOFORCE
Unlocks the directory by decrementing the lock reference count. The lock reference count must return to 0, or the directory will remain locked.
REPL_UNLOCK_FORCE
Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplImportDirLock


NetReplSetInfo

The NetReplSetInfo function modifies the Replicator service configuration information.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetReplSetInfo.

NET_API_STATUS NetReplSetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of REPL_INFO_0 structures.
1000 | The buf parameter points to an array of REPL_INFO_1000 structures.
1001 | The buf parameter points to an array of REPL_INFO_1001 structures.
1002 | The buf parameter points to an array of REPL_INFO_1002 structures.
1003 | The buf parameter points to an array of REPL_INFO_1003 structures.

buf
Pointer to the buffer in which data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the identifier of the first parameter that caused ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetReplGetInfo, REPL_INFO_0, REPL_INFO_1000, REPL_INFO_1001, REPL_INFO_1002, REPL_INFO_1003


NetScheduleJobAdd

The NetScheduleJobAdd function submits a job to run at a specified future time and date. This function requires that the Schedule service be started at the computer to which the job is submitted.

Security Requirements

Only members of the Administrators local group can successfully execute NetScheduleJobAdd on a remote server.

NET_API_STATUS NetScheduleJobAdd(
  LPWSTR Servername,
  LPBYTE Buffer,
  LPDWORD JobId
);

Parameters

Servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
Buffer
Pointer to a buffer containing an AT_INFO structure describing the job to be submitted.
JobId
Pointer to a job identifier for a newly submitted job. This entry is valid only if the function returns successfully.

Remarks

If you set DaysOfMonth and DaysOfWeek to zero, then the job executes only once, the first time JobTime at the server is reached. After being executed, the job will be deleted.

If one sets bits in DaysOfMonth and/or DaysOfWeek, but do not set the bit flag JOB_RUN_PERIODICALLY, a job will execute at JobTime once for each day listed in days bitmasks. See the AT_INFO structure for a descritpion of the bitmasks. After each execution, the corresponding bit in days bitmasks will be cleared. Once the last bit in days bitmasks is cleared, the job will be deleted.

If one sets bits in DaysOfMonth and/or DaysOfWeek, and at the same time set the bit flag JOB_RUN_PERIODICALLY, a job executes at JobTime whenever a day with the corresponding bit in days bitmasks is reached. See the AT_INFO structure for a descritpion of the bitmasks. This job is thus executed periodically and does not get deleted as a result of repeated executions. The only way to delete this job is by an explicit call to NetScheduleJobDel.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetScheduleJobDel

The NetScheduleJobDel function deletes a range of jobs queued to run at a computer. This function requires that the Schedule service be started at the computer to which the job deletion request is being sent.

Security Requirements

Only members of the Administrators local group can successfully execute NetScheduleJobDel on a remote server.

NET_API_STATUS NetScheduleJobDel(
  LPWSTR Servername,
  DWORD MinJobId,
  DWORD MaxJobId
);

Parameters

Servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
MinJobId
Minimum job identifier. Jobs with a job identifier smaller than MinJobId will not be deleted.
MaxJobId
Maximum job identifier. Jobs with job identifier bigger than MaxJobId will not be deleted.

Remarks

This function deletes all jobs whose job identifier is in the range MinJobId through MaxJobId. To delete all jobs at the server, you can call this function with MinJobId equal to 0 and MaxJobId equal to (DWORD) – 1. To delete just one particular job, you can choose MinJobId and MaxJobId both equal to the identifier for that job.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetScheduleJobAdd


NetScheduleJobEnum

The NetScheduleJobEnum function lists the jobs queued on a specified computer. This function requires that the Schedule service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetScheduleJobEnum on a remote server.

NET_API_STATUS NetScheduleJobEnum(
  LPWSTR Servername,
  LPBYTE *PointerToBuffer,
  DWORD PreferredMaximumLength,
  LPDWORD EntriesRead,
  LPDWORD TotalEntries,
  LPDWORD ResumeHandle
);

Parameters

Servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
PointerToBuffer
On return a pointer to the return information structure is returned in the address pointed to by PointerToBuffer. The return information structure is an array of AT_ENUM data structures.
PreferredMaximumLength
Preferred maximum length, in 8-bit bytes of returned data.
EntriesRead
Pointer to a DWORD that contains the actual enumerated element count.
TotalEntries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
ResumeHandle
Pointer to a DWORD that contains ResumeHandle, which is used to continue an job enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.

Note Each entry returned contains the JobId number of the AT_ENUM structure. The value of this member can be used in functions that require job identifier argument, such as NetScheduleJobDel.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetScheduleJobGetInfo


NetScheduleJobGetInfo

The NetScheduleJobGetInfo function retrieves information about a particular job queued on a specified computer. This function requires that the Schedule service be started.

Security Requirements

Only members of the Administrators local group can successfully execute NetScheduleJobGetInfo on a remote server.

NET_API_STATUS NetScheduleJobGetInfo(
  LPWSTR Servername,
  DWORD JobId,
  LPBYTE *PointerToBuffer
);

Parameters

Servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
JobId
A job identifier of a job in question.
PointerToBuffer
On return a pointer to the buffer containing the AT_INFO structure describing the job in question.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetScheduleJobEnum


NetServerDiskEnum

The NetServerDiskEnum function retrieves a list of disk drives on a server. This function returns its result as an array of three-character strings (drive letter, colon, NULL).

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetServerDiskEnum on a remote computer. No special group membership is required for local calls.

NET_API_STATUS NetServerDiskEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies only the value of zero for bufptr.
bufptr
Pointer to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resume_handle
Pointer to a DWORD that contains resume_handle, which is used to continue an existing server disk search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerEnum, SERVER_INFO_100


NetServerEnum

The NetServerEnum function lists all servers of the specified type that are visible in the specified domain. For example, an application can call NetServerEnum to list all domain controllers only or all SQL servers only.

You can combine bit masks to list several types. For example, a value of 0x00000003 combines the bit masks for SV_TYPE_WORKSTATION (0x00000001) and SV_TYPE_SERVER (0x00000002).

Note If you require more information on the type, name, and comment for a specific server, use the WNetEnumResource function.

Security Requirements

No special group membership is required to successfully execute NetServerEnum.

NET_API_STATUS NetServerEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  DWORD servertype,
  LPWSTR domain,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
100 | The bufptr parameter points to an array of SERVER_INFO_100 structures.
101 | The bufptr parameter points to an array of SERVER_INFO_101 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
On return, the actual enumerated element count is located in the doubleword pointed to by entriesread.
totalentries
Returns the total number of visible servers and workstations on the network.
servertype
A DWORD mask that filters server entries to return from the enumeration. The defined mask bits specify:
Symbolic constant | Value | Meaning
SV_TYPE_WORKSTATION | 0x00000001 | All Net workstations
SV_TYPE_SERVER | 0x00000002 | All Net servers
SV_TYPE_SQLSERVER | 0x00000004 | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | 0x00000008 | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | 0x00000010 | Backup domain controller
SV_TYPE_TIMESOURCE | 0x00000020 | Server running the Timesource service
SV_TYPE_AFP | 0x00000040 | Apple File Protocol servers
SV_TYPE_NOVELL | 0x00000080 | Novell servers
SV_TYPE_DOMAIN_MEMBER | 0x00000100 | LAN Manager 2.x Domain Member
SV_TYPE_LOCAL_LIST_ONLY | 0x40000000 | Servers maintained by the browser. See the following Remarks section.
SV_TYPE_PRINT | 0x00000200 | Server sharing print queue
SV_TYPE_DIALIN | 0x00000400 | Server running dial-in service
SV_TYPE_XENIX_SERVER | 0x00000800 | Xenix server
SV_TYPE_MFPN | 0x00004000 | Microsoft File and Print for Netware
SV_TYPE_NT | 0x00001000 | Windows NT (either Workstation or Server)
SV_TYPE_WFW | 0x00002000 | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | 0x00008000 | Windows NT Non-DC server
SV_TYPE_POTENTIAL_BROWSER | 0x00010000 | Server that can run the Browser service
SV_TYPE_BACKUP_BROWSER | 0x00020000 | Server running a Browser service as backup
SV_TYPE_MASTER_BROWSER | 0x00040000 | Server running the master Browser service
SV_TYPE_DOMAIN_MASTER | 0x00080000 | Server running the domain master Browser
SV_TYPE_DOMAIN_ENUM | 0x80000000 | Primary Domain
SV_TYPE_WINDOWS | 0x00400000 | Windows 95 or later
SV_TYPE_ALL | 0xFFFFFFFF | All servers

domain
A pointer to a Unicode string containing the name of the domain for which a list of servers is to returned. If NULL is specified, the primary domain is implied.
resume_handle
Reserved. Must be set to zero. Use the Wnet functions.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes:

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_NO_BROWSER_SERVERS_FOUND | No browser servers found.
ERROR_MORE_DATA | More entries are available with subsequent calls.

Remarks

The SV_TYPE_LOCAL_LIST_ONLY flag returns the list of servers maintained by the browser internally. This has meaning only on the master browser (or on a computer that has been the master browser in the past). The master browser is the machine that currently has rights to determine which machines can be servers or workstations on the net.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerDiskEnum, NetQueryDisplayInformation


NetServerGetInfo

The NetServerGetInfo function retrieves information about the specified server.

Security Requirements

Only the Administrators or Accounts Operators local group, or those with Communication, Print, or Server operator group membership can successfully execute NetServerGetInfo at level 102 or higher. No special group membership is required for level 100 or level 101 calls.

NET_API_STATUS NetServerGetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
100 | The bufptr parameter points to an array of SERVER_INFO_100 structures.
101 | The bufptr parameter points to an array of SERVER_INFO_101 structures.
102 | The bufptr parameter points to an array of SERVER_INFO_102 structures.

The preceding levels are valid for all platforms. The following levels are valid only for the appropriate platforms.
Value | Meaning
402 | The buf parameter points to an array of SERVER_INFO_402 structures.
403 | The buf parameter points to an array of SERVER_INFO_403 structures.
502 | The buf parameter points to an array of SERVER_INFO_502 structures.
503 | The buf parameter points to an array of SERVER_INFO_503 structures.

bufptr
Pointer to the buffer in which the data requested with the level parameter is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetServerSetInfo, SERVER_INFO_100, SERVER_INFO_101, SERVER_INFO_102, SERVER_INFO_402, SERVER_INFO_403, SERVER_INFO_502, SERVER_INFO_503


NetServerSetInfo

The NetServerSetInfo function sets a server's operating parameters; it can set them individually or collectively. This information is stored in a way that allows it to remain in effect after the system has been reinitialized.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetServerSetInfo.

NET_API_STATUS NetServerSetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD ParmError
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Level of information to set. SERVER_INFO_100, SERVER_INFO_101, and SERVER_INFO_102 are valid for all platforms. SERVER_INFO_402, SERVER_INFO_403, SERVER_INFO_502 and SERVER_INFO_509 are valid for the appropriate platform. In addition, SERVER_INFO_1001 – SERVER_INFO_1006, SERVER_INFO_1009 – SERVER_INFO_1011, SERVER_INFO_1016 – SERVER_INFO_1018, SERVER_INFO_1021, SERVER_INFO_1022, SERVER_INFO_1028, SERVER_INFO_1029, and SERVER_INFO_1037 – SERVER_INFO_1043 are valid based on the restrictions for LAN Manager systems described NetServerGetInfo.
buf
Pointer to a buffer containing the server information.
ParmError
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerGetInfo


NetServerTransportAdd

The NetServerTransportAdd function binds the server to the transport.

Security Requirements

Only members of the Administrators local group can successfully execute NetServerTransportAdd.

NET_API_STATUS NetServerTransportAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to set the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of SERVER_TRANSPORT_INFO_0 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_DUP_NAME | A duplicate name exists on the network.
ERROR_INVALID_DOMAINNAME | The domain name could not be found on the network.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerTransportDel, SERVER_TRANSPORT_INFO_0


NetServerTransportDel

The NetServerTransportDel function unbinds (or disconnects) the transport protocol from the server. Effectively, the server can no longer communicate with clients using the transport protocol. The server will no longer process client request from the active transport protocol, such as TCP, NetBEUI, and XNS.

Security Requirements

Only members of the Administrators local group can successfully execute NetServerTransportDel.

NET_API_STATUS NetServerTransportDel(
  LPWSTR servername,
  LPWSTR transportname
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
transportname
Pointer to a Unicode string containing the name of the transport protocol from which to unbind.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NetNameNotFound | The sharename does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerTransportAdd


NetServerTransportEnum

The NetServerTransportEnum function supplies information about transports that are managed by the server.

Security Requirements

No special group membership is required to successfully execute NetServerTransportEnum.

NET_API_STATUS NetServerTransportEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Level of information required. Only zero is valid.
bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumehandle
Pointer to a DWORD that contains resumehandle, which is used to continue an existing server transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetServiceControl

The NetServiceControl function is obsolete. It is included for compatability with 16-bit versions of Windows. Win32-based applications should use the service functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetServiceEnum

The NetServiceEnum function is obsolete. It is included for compatability with 16-bit versions of Windows. Win32-based applications should use the service functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetServiceGetInfo

The NetServiceGetInfo function is obsolete. It is included for compatability with 16-bit versions of Windows. Win32-based applications should use the service functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetServiceInstall

The NetServiceInstall function is obsolete. It is included for compatability with 16-bit versions of Windows. Win32-based applications should use the service functions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetSessionDel

The NetSessionDel function ends a session between a server and a workstation.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetSessionDel.

NET_API_STATUS NetSessionDel(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
UncClientName
Pointer to a Unicode string containing the computer name of the client to disconnect. If UncClientName is NULL, then all the sessions of the user in username will be deleted on the server specified.
username
Pointer to a Unicode string containing the name of the user whose session is to be terminated. A NULL pointer indicates that all users' sessions from the client name specified are to be terminated.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | The specified computer does not have a session with the computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetSessionEnum, NetSessionGetInfo


NetSessionEnum

The NetSessionEnum function provides information about all current sessions.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetSessionEnum at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

NET_API_STATUS NetSessionEnum(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
UncClientName
Pointer to a Unicode string containing the name of the computer session for which information is to be returned. A NULL pointer or string specifies that all computer sessions on the server are to be enumerated.
username
Pointer to a Unicode string containing the name of the the user for which to enumerate the sessions. A NULL pointer or string specifies that sessions for all users are to be enumerated.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of SESSION_INFO_0 structures.
1 | The bufptr parameter points to an array of SESSION_INFO_1 structures.
2 | The bufptr parameter points to an array of SESSION_INFO_2 structures.
10 | The bufptr parameter points to an array of SESSION_INFO_10 structures.
502 | The bufptr parameter points to an array of SESSION_INFO_502 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resume_handle
Pointer to a DWORD that contains resume_handle, which is used to continue an existing session search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, no resume handle is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | The specified computer does not have a session with the computer.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetSessionGetInfo, SESSION_INFO_0, SESSION_INFO_1, SESSION_INFO_2, SESSION_INFO_10, SESSION_INFO_502


NetSessionGetInfo

The NetSessionGetInfo function retrieves information about a session established between a particular server and workstation.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetSessionGetInfo at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

NET_API_STATUS NetSessionGetInfo(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
UncClientName
Pointer to a Unicode string containing the name of the computer session for which information is to be returned. This parameter cannot be NULL.
username
Pointer to a Unicode string containing the name of the user whose session information is to be returned. This parameter cannot be NULL.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of SESSION_INFO_0 structures.
1 | The bufptr parameter points to an array of SESSION_INFO_1 structures.
2 | The bufptr parameter points to an array of SESSION_INFO_2 structures.
10 | The bufptr parameter points to an array of SESSION_INFO_10 structures.

bufptr
Points to the buffer in which the data set with the level parameter is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | The specified computer does not have a session with the computer.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetSessionDel, NetSessionEnum, SESSION_INFO_0, SESSION_INFO_1, SESSION_INFO_2, SESSION_INFO_10


NetShareAdd

The NetShareAdd function shares a server resource.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute NetShareAdd. The Print operator can add only Printer queues. The Communication operator can add only communication-device queues.

NET_API_STATUS NetShareAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
2 | The buf parameter points to an array of SHARE_INFO_2 structures.
502 | The buf parameter points to an array of SHARE_INFO_502 structures.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_NAME | The character or file system name is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
NERR_DuplicateShare | The sharename is already in use on this server.
NERR_RedirectedPath | The operation is invalid for a redirected resource. The specified device name is assigned to a shared resource.
NERR_UnknownDevDir | The device or directory does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetShareDel


NetShareCheck

The NetShareCheck function checks whether or not a server is sharing a device.

Security Requirements

No special group membership is required to successfully execute NetShareCheck.

NET_API_STATUS NetShareCheck(
  LPWSTR servername,
  LPWSTR device,
  LPDWORD type
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
device
Pointer to a Unicode string containing the name of the device to check for shared access.
type
Pointer to an address that contains the type of device share. On return the address pointed to by the type parameter contains the type of share the device is offered with. This parameter is set only if the function returned successfully.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_DeviceNotShared | The device is not shared.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetShareEnum, NetShareGetInfo


NetShareDel

The NetShareDel function deletes a share name from a server's list of shared resources, disconnecting all connections to the shared resource.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute NetShareDel. The Print operator can delete only Printer queues. The Communication operator can delete only communication-device queues.

NET_API_STATUS NetShareDel(
  LPWSTR servername,
  LPWSTR netname,
  DWORD reserved
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
netname
Pointer to a Unicode string containing the network name of the share to delete.
reserved
Reserved, must be zero.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NetNameNotFound | The sharename does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetShareAdd


NetShareEnum

NetShareEnum retrieves information about each shared resource on a server. The NetShareEnum function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareEnum at level 2. No special group membership is required for level 0 or level 1 calls.

NET_API_STATUS NetShareEnum(
  LPWSTR servername,
  DWORD level,
  LPTBYTE * bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle,
);

Parameters

servername
A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Level of information required. 0, 1, 2, and 502 are valid.
bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen
Prefered maximum length of returned data (in 8-bit bytes).
entriesread
On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries
On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resume_handle
On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing share search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetShareGetInfo

The NetShareGetInfo function retrieves information about a particular shared resource on a server.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute NetShareGetInfo at level 2. No special group membership is required for calls in SHARE_INFO_0 and SHARE_INFO_1.

NET_API_STATUS NetShareGetInfo(
  LPWSTR servername,
  LPWSTR netname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
netname
Pointer to a Unicode string containing the network name of the share on which to return information.
level
Specifies one of the following values to return the level of information available.
Value | Meaning
0 | The bufptr parameter points to an array of SHARE_INFO_0 structures.
1 | The bufptr parameter points to an array of SHARE_INFO_1 structures.
2 | The bufptr parameter points to an array of SHARE_INFO_2 structures.
501 | The bufptr parameter points to an array of SHARE_INFO_501 structures.
502 | The bufptr parameter points to an array of SHARE_INFO_502 structures.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.
NERR_NetNameNotFound | The sharename does not exist.

Remarks

You need to free the memory pointed to by bufptr. Use the NetAPIBufferFree function to free the pointer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions


NetShareSetInfo

The NetShareSetInfo function sets the parameters of a shared resource.

Security Requirements

Only the Administrators local group or Communication, Print, or Server operator group membership is required to successfully execute NetShareSetInfo. The Print operator can set information only about Printer queues. The Communication operator can set information only about communication-device queues.

NET_API_STATUS NetShareSetInfo(
  LPWSTR servername,
  LPWSTR netname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
netname
Pointer to a Unicode string containing the network name of the share to set information on.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
1 | The buf parameter points to an array of SHARE_INFO_1 structures.
2 | The buf parameter points to an array of SHARE_INFO_2 structures.
502 | The buf parameter points to an array of SHARE_INFO_502 structures.
1004 | The buf parameter points to an array of SHARE_INFO_1004 structures.
1006 | The buf parameter points to an array of SHARE_INFO_1006 structures.
1501 | The buf parameter points to an array of SHARE_INFO_1501 structures.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
NERR_NetNameNotFound | The sharename does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.
Import Library: Use netapi32.lib (Windows NT) or svrapi.lib (Windows 95).

See Also

Networking (Net) Overview, Net Functions, NetShareGetInfo


NetStatisticsGet

The NetStatisicsGet function is obsolete. Win32-based applications should use the NetStatisticsGet2 function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmstats.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetStatisticsGet2

NetStatisticsGet2 retrieves operating statistics for a service. Currently, only the Workstation and Server services are supported.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetStatisticsGet2 on a remote server.

NET_API_STATUS NetStatisticsGet2(
  LPWSTR server,
  LPWSTR service,
  DWORD level,
  DWORD options,
  LPBYTE *bufptr
);

Parameters

server
Pointer to a Unicode string that contains the name of the server on which to execute NetStatisticsGet2. A NULL pointer or null string specifies the local computer.
service
Pointer to a Unicode string that contains the name of the service about which to get the statistics. Only the values SERVER and WORKSTATION are currently allowed.
level
Specifies the following value to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of STAT_WORKSTATION_0 or STAT_SERVER_0 structures.

options
Must be zero.
bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmstats.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetServerGetInfo, STAT_SERVER_0, STAT_WORKSTATION_0


NetUseAdd

NetUseAdd establishes a connection between a local or NULL device name and a shared resource by redirecting the local or NULL (UNC) device name to the shared resource. The NetUseAdd function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetAddConnection2 function.

Security Requirements

No special group membership is required for this call. This function cannot be executed on a remote server.

NET_API_STATUS NetUseAdd (
  LPWSTR UncServerName,
  DWORD Level,
  LPBYTE Buf,
  LPDWORD ParmError
);

Parameters

UncServerName
Must be NULL.
Level
Level of information to set. 1 and 2 are valid.
Buf
A pointer to a buffer containing the use information structure.
ParmError
Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, WNetAddConnection2


NetUseDel

The NetUseDel function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the WNetCancelConnection2 function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetUseEnum

The NetUseEnum function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetUseGetInfo

The NetUseGetInfo function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the WNetGetConnection function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions


NetUserAdd

The NetUserAdd function adds a user account and assigns a password and privilege level.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserAdd. Only members of the Administrators local group can add an Administrators privilege account.

NET_API_STATUS NetUserAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
1 | The buf parameter points to a USER_INFO_1 structure.
2 | The buf parameter points to a USER_INFO_2 structure.
3 | The buf parameter points to a USER_INFO_3 structure.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function returns account information, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | Thiecomputer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupExists | The group already exists.
NERR_UserExists | The user account already exists.
NERR_PasswordTooShort | The password is shorter than required. The password could also have been too long, too recent in its change history, not enough unique characters, or some other faulty indication of password restrictions.

Remarks

Server users must use a system in which the server creates a WINDOWS NT system account for the new user. The creation of this account is controlled by several parameters in the server's LANMAN.INI file.

If the newly added server user name already exists as a Windows NT system user, the useril_home_dir member of the USER_INFO_1 structure is ignored. The NetUserAdd function supports USER_INFO_1 and USER_INFO_2 structures. Using members of USER_INFO_1 initializes default values in USER_INFO_2 and USER_INFO_3 structures.

Subsequent NetUserSetInfo calls can change the default values. The following are possible default values.

Member | Default Value
usriX_auth_flags | None (0)
usriX_full_name | usri1_name
usriX_usr_comment | None (null string)
usriX_parms | None (null string)
usriX_workstations | All (null string)
usriX_acct_expires | Never (TIMEQ_FOREVER)
usriX_max_storage | Unlimited (USER_MAXSTORAGE_UNLIMITED)
usriX_logon_hours | Logon allowed at any time (each element 0xFF; all bits set to 1)
usriX_logon_server | Any domain controller (\\*)
usriX_country_code | Current (country_code on the server
usriX_code_page | 0

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserEnum, NetUserSetInfo, NetUserDel


NetUserChangePassword

The NetUserChangePassword function changes a user's password for a specified network server or domain.

Security Requirements

A server or domain can be configured to require a user to log on before changing the password on a user account. In that case, only members of the Administrators or Account Operators local group or the user himself can change the password for a user account. If logging on is not required, the user can change the password for any user account, as long as the user knows the current password.

NET_API_STATUS NetUserChangePassword(
  LPWSTR domainname,
  LPWSTR username,
  LPWSTR oldpassword,
  LPWSTR newpassword
);

Parameters

domainname
Pointer to a null-terminated Unicode string that specifies the name of a remote server or domain. The NetUserChangePassword function changes the user's password on that remote server or domain.

A value of NULL in the domainname parameter specifies the logon domain of the caller.

username
Pointer to a null-terminated Unicode string that specifies a user name. The NetUserChangePassword function changes the password for that user.

A value of NULL in the username parameter specifies the logon user name of the caller.

oldpassword
Pointer to a null-terminated Unicode string that specifies the user's old password on the server or domain.
newpassword
Pointer to a null-terminated Unicode string that specifies the user's new password on the server or domain.

Return Values

If the function is successful, it returns account information and the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PASSWORD | The user has entered an invalid password.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_UserNotFound | The user name could not be found.
NERR_PasswordTooShort | The password is shorter than required. The password could also have been too long, too recent in its change history, not enough unique characters, or some other faulty indication of password restrictions.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserSetInfo


NetUserDel

The NetUserDel function deletes a user account from a server.

Requirements

Only members of the Administrators or the Account Operators local group can successfully execute NetUserDel on a remote server or on a computer that has local security enabled. Only members of the Administrators local group can delete an Administrators privilege account.

NET_API_STATUS NetUserDel(
  LPWSTR servername,
  LPWSTR username
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
username
Pointer to a Unicode string containing the name of the user account to delete.

Remarks

An account cannot be deleted while a user or application is using a server resource. If the user was added to the system through the server with the NetUserAdd function, deleting the user deletes the user's Windows NT system account.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, NetApiBufferFree


NetUserEnum

The NetUserEnum function provides information about all user accounts on a server.

Security Requirements

Only members of the Administrators or Account operators local group can successfully execute NetUserEnum at levels 1 and 2. No special group membership is required at level 0 or 10.

NET_API_STATUS NetUserEnum(
  LPWSTR servername,
  DWORD level,
  DWORD filter,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of USER_INFO_0 structures.
1 | The bufptr parameter points to an array of USER_INFO_1 structures.
2 | The bufptr parameter points to an array of USER_INFO_2 structures.
3 | The bufptr parameter points to an array of USER_INFO_3 structures.
10 | The bufptr parameter points to an array of USER_INFO_10 structures.
11 | The bufptr parameter points to an array of USER_INFO_11 structures.
20 | The bufptr parameter points to an array of USER_INFO_20 structures.

filter
Specifies a filter of account types to enumerate. A value of zero implies all account types. Allowable values are:
Value | Meaning
FILTER_TEMP_DUPLICATE_ACCOUNTS | Enumerates local user account data on a domain controller.
FILTER_NORMAL_ACCOUNT | Enumerates global user account data on a computer.
FILTER_INTERDOMAIN_TRUST_ACCOUNT | Enumerates domain trust account data on a domain controller.
FILTER_WORKSTATION_TRUST_ACCOUNT | Enumerates workstation or member server account data on a domain controller.
FILTER_SERVER_TRUST_ACCOUNT | Enumerates domain controller account data on a domain controller.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored. The returned buffer should be deallocated using the NetApiBufferFree function.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position. EXCEPTION: If the call is to a computer that is running LAN Manager 2.x, the totalentries parameter will always reflect the total number of entries in the database no matter where it is in the resume sequence.
resume_handle
Pointer to a DWORD that contains resume_handle, which is used to continue an existing user search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available with subsequent calls.

Remarks

The NetUserEnum function returns the full set of USER_INFO_0 or USER_INFO_1 components. If level is set to 1, the password component of each data structure will be set to NULL to maintain password security. The NetUserEnum does not return all Windows NT system users. It returns only those users who have been added by the NetUserAdd function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserGetGroups, NetUserGetInfo, USER_INFO_0, USER_INFO_1, NetUserAdd


NetUserGetGroups

The NetUserGetGroups function retrieves a list of global groups to which a specified user belongs.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserGetGroups or on a computer that has local security enabled, except when users request details about their own accounts.

NET_API_STATUS NetUserGetGroups(
  LPWSTR servername,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the server program running on the local computer.
username
Pointer to a Unicode string containing the name of the user to search for in each group account.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to an array of GROUP_USERS_INFO_0 structures.
1 | The bufptr parameter points to an array of GROUP_USERS_INFO_1 structures.

bufptr
Pointer to a pointer which receives the address of the returned data set with the level parameter. You do not need to allocate buffer space. However, the returned buffer should be deallocated using the NetApiBufferFree function.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

The NetUserGetGroups function returns an array of GROUP_INFO_0 structure, that specifies the names of all groups to which the user belongs. Net groups are separate and distinct from Windows NT system groups.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserGetInfo


NetUserGetInfo

The NetUserGetInfo function retrieves information about a particular user account on a server.

Security Requirements

No special group membership is required to successfully execute NetUserGetInfo. This is a change from LAN Manager, which required membership in the Administrators or Account Operators local group to call this function at information levels above 0 (except for the user's own account, which could use level 11).

NET_API_STATUS NetUserGetInfo(
  LPWSTR servername,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
username
Pointer to a Unicode string containing the name of the user account on which to return information.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | Returns USER_INFO_0 structure pointed to in bufptr.
1 | Returns USER_INFO_1 structure pointed to in bufptr.
2 | Returns USER_INFO_2 structure pointed to in bufptr.
3 | Returns USER_INFO_3 structure pointed to in bufptr.
10 | Returns USER_INFO_10 structure pointed to in bufptr.
11 | Returns USER_INFO_11 structure pointed to in bufptr.
20 | Returns USER_INFO_20 structure pointed to in bufptr.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored. The returned buffer should be deallocated using the NetApiBufferFree function.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferFree, NetUserSetInfo, NetUserGetGroups, NetUserEnum


NetUserGetLocalGroups

The NetUserGetLocalGroups function retrieves a list of local groups to which a specified user belongs.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserGetLocalGroups.

NET_API_STATUS NetUserGetLocalGroups(
  LPWSTR servername,
  LPWSTR username,
  DWORD level,
  DWORD flags,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
username
Pointer to a Unicode string containing the name of the user for which to return global group membership. This parameter can be of the form <UserName>, in which case the username is expected to be found on servername. The user name can also be of the form <DomainName>\<UserName> in which case <DomainName> is associated with servername and <UserName> is expected to be to be found on that domain.
level
Level of information required. Only 0 is valid.
flags
Bitmask of flags. Currently, only LG_INCLUDE_INDIRECT is defined. If this bit is set, the function will also return the local groups of which the user is indirectly a member (that is, by the virtue of being in a global group that itself is a member of one or more local groups).
bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned information is an array of LOCALGROUP_USERS_INFO_0 structures. The returned buffer should be deallocated using the NetApiBufferFree function.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetApiBufferFree


NetUserModalsGet

The NetUserModalsGet function retrieves global information for all users and global groups in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserModalsGet.

NET_API_STATUS NetUserModalsGet(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to a USER_MODALS_INFO_0 structure.
1 | The bufptr parameter points to a USER_MODALS_INFO_1 structure.
2 | The bufptr parameter points to a USER_MODALS_INFO_2 structure.
3 | The bufptr parameter points to a USER_MODALS_INFO_3 structure.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored. The returned buffer should be deallocated using the NetApiBufferFree function.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserModalsSet, NetApiBufferFree


NetUserModalsSet

The NetUserModalsSet function sets global information for all users and global groups in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserModalsSet.

NET_API_STATUS NetUserModalsSet(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to a USER_MODALS_INFO_0 structure.
1 | The buf parameter points to a USER_MODALS_INFO_1 structure.
2 | The buf parameter points to a USER_MODALS_INFO_2 structure.
3 | The buf parameter points to a USER_MODALS_INFO_3 structure.
1001 | The buf parameter points to a USER_MODALS_INFO_1001 structure.
1002 | The buf parameter points to a USER_MODALS_INFO_1002 structure.
1003 | The buf parameter points to a USER_MODALS_INFO_1003 structure.
1004 | The buf parameter points to a USER_MODALS_INFO_1004 structure.
1005 | The buf parameter points to a USER_MODALS_INFO_1005 structure.
1006 | The buf parameter points to a USER_MODALS_INFO_1006 structure.
1007 | The buf parameter points to a USER_MODALS_INFO_1007 structure.

buf
Points to the buffer in which the data set with the level parameter is stored. The returned buffer should be deallocated using the NetApiBufferFree function.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserModalsGet, NetApiBufferFree


NetUserSetGroups

The NetUserSetGroups function sets global group memberships for a specified user account.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserSetGroups.

NET_API_STATUS NetUserSetGroups(
  LPWSTR servername,
  LPWSTR username,
  DWORD level,
  LPBYTE buf,
  DWORD num_entries
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
username
Pointer to a Unicode string containing the name of the user for which to set global group memberships.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to an array of GROUP_USERS_INFO_0 structures.
1 | The buf parameter points to an array of GROUP_USERS_INFO_1 structures.

buf
Pointer to the buffer in which the data set with the level parameter is stored.
num_entries
Number of global group information structures contained in the array pointed to by buf.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserGetGroups


NetUserSetInfo

The NetUserSetInfo function sets the parameters of a user account.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetUserSetInfo on a remote server or on a computer that has local security enabled. A user may call NetUserSetInfo to set certain information on his or her own account.

NET_API_STATUS NetUserSetInfo(
  LPWSTR servername,
  LPWSTR username,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
username
Pointer to a Unicode string containing the name of the user account to set information.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to a USER_INFO_0 structure.
1 | The buf parameter points to a USER_INFO_1 structure.
2 | The buf parameter points to a USER_INFO_2 structure.
3 | The buf parameter points to a USER_INFO_3 structure.
21 | The buf parameter points to a USER_INFO_21 structure.
22 | The buf parameter points to a USER_INFO_22 structure.
1003 | The buf parameter points to a USER_INFO_1003 structure.
1005 | The buf parameter points to a USER_INFO_1005 structure.
1006 | The buf parameter points to a USER_INFO_1006 structure.
1007 | The buf parameter points to a USER_INFO_1007 structure.
1008 | The buf parameter points to a USER_INFO_1008 structure.
1009 | The buf parameter points to a USER_INFO_1009 structure.
1010 | The buf parameter points to a USER_INFO_1010 structure.
1011 | The buf parameter points to a USER_INFO_1011 structure.
1012 | The buf parameter points to a USER_INFO_1012 structure.
1013 | The buf parameter points to a USER_INFO_1013 structure.
1014 | The buf parameter points to a USER_INFO_1014 structure.
1017 | The buf parameter points to a USER_INFO_1017 structure.
1020 | The buf parameter points to a USER_INFO_1020 structure.
1024 | The buf parameter points to a USER_INFO_1024 structure.
1051 | The buf parameter points to a USER_INFO_1051 structure.
1053 | The buf parameter points to a USER_INFO_1053 structure.

buf
Pointer to the buffer in which the data set with the level parameter is stored. The returned buffer should be deallocated using the NetApiBufferFree function.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL the parameter is not returned on error.

Remarks

The NetUserSetInfo function can be called to change a user's password only by users or applications having administrative privileges. However, the password can be changed by users or applications knowing the current password and calling NetUserChangePassword. When an administrator calls NetUserSetInfo, the only restriction applied is that the new password length must be consistent with system modals.

Members of the Administrators local group can set any modifiable element. All users can set the usri2_usr_comment, usri2_parms, and usri2_country_code, elements of the user_info_2 data structure for their own accounts. To do this, the user must use the ParmNum parameter and cannot pass the whole structure.

A member of the Account Operator's local group cannot set details for an Administrators class account, give an existing account Administrator privilege, or change the operator privilege of any account. If attempting to change the privilege level or disable the last account with Administrator privilege in the database, NetUserSetInfo fails and returns NERR_LastAdmin.

You can call NetUserSetInfo with USER_INFO_1 and specify a value using the usri1_name member. However, that value will be ignored. The correct way to specify the new name of the group is to call NetUserSetInfo with USER_INFO_0 and specify a value using the usri0_name member.

The NetUserSetInfo function cannot be used to change the home directory for user accounts that were not created by the Net server.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.
NERR_LastAdmin | The operation is not allowed on the last administrative account.
NERR_BadPassword | The share name or password is invalid.
NERR_PasswordTooShort | The password is shorter than required.
NERR_UserNotFound | The user name could not be found.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetUserGetInfo


NetWkstaGetInfo

The NetWkstaGetInfo function returns information about the configuration elements for a workstation.

Security Requirements

You must have Print or Server operator privilege, or be a member of the Administrator or Account local groups to successfully execute NetWkstaGetInfo at level 0 or level 1 on a remote server. No special privilege is required for level 10 calls.

NET_API_STATUS NetWkstaGetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
100 | The bufptr parameter points to a WKSTA_INFO_100 structure.
101 | The bufptr parameter points to a WKSTA_INFO_101 structure.
102 | The bufptr parameter points to a WKSTA_INFO_102 structure.
302 | The bufptr parameter points to a WKSTA_INFO_302 structure.
402 | The bufptr parameter points to an WKSTA_INFO_402 structure.
502 | The bufptr parameter points to a WKSTA_INFO_502 structure. It is not advisable to change the values of WKSTA_INFO_502.

bufptr
Pointer to the buffer in which the data set with the level parameter is stored.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaSetInfo


NetWkstaSetInfo

The NetWkstaSetInfo function configures a workstation. This information remains in effect after the system has been reinitialized.

Security Requirements

Only members of the Administrators local group can successfully execute NetWkstaSetInfo on a remote server.

NET_API_STATUS NetWkstaSetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE buffer,
  LPDWORD parm_err
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
100 | The buffer parameter points to a WKSTA_INFO_100 structure.
101 | The buffer parameter points to a WKSTA_INFO_101 structure.
102 | The buffer parameter points to a WKSTA_INFO_102 structure.
302 | The buffer parameter points to a WKSTA_INFO_302 structure.
402 | The buffer parameter points to a WKSTA_INFO_402 structure.
1101 | The buffer parameter points to a WKSTA_USER_INFO_1101 structure.

In addition, the structures WKSTA_USER_INFO_502, WKSTA_USER_INFO_1010-1013, WKSTA_USER_INFO_1018, WKSTA_USER_INFO_1023, WKSTA_USER_INFO_1027, WKSTA_USER_INFO_1028, WKSTA_USER_INFO_1032, WKSTA_USER_INFO_1033, WKSTA_USER_INFO_1035, and WKSTA_USER_INFO_1041-1062 should not be set by the user.

buffer
Pointer to the buffer in which the data set with the level parameter is stored.
parm_num
Determines whether the buffer parameter contains a complete WKSTA_INFO_X (where Xis the level) structure or a single structure component. If parm_num is set to PARMNUM_ALL, buffer must point to a WKSTA_INFO_X structure. Otherwise, only one element is changed, and parm_num must point to the single element to change.

Not all elements can be changed. Only those elements that have a specific PARMNUM constant value defined can be set. The following possible values are defined.
Value | Component to Set
PARMNUM_ALL | All elements
WKSTA_CHARWAIT_PARMNUM | wki0_charwait
WKSTA_CHARTIME_PARMNUM | wki0_chartime
WKSTA_CHARCOUNT_PARMNUM | wki0_charcount
WKSTA_ERRLOGSZ_PARMNUM | wki0_errlogsz
WKSTA_PRINTBUFTIME_PARMNUM | wki0_printbuftime
WKSTA_WRKHEURISTICS_PARMNUM | wki0_wrkheuristics
WKSTA_OTHDOMAINS_PARMNUM | wki1_oth_domains

parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

Remarks

You must be a member of the Administrators local group to successfully execute NetWkstaSetInfo on a remote server or on a computer that has local security enabled. NetWkstaSetInfo does not change values in the LANMAN.INI file. Values set by previous calls to NetWkstaSetInfo can be overwritten when workstation parameters are reset. When the Workstation service is stopped and restarted, parameters are reset to the default values specified in the LANMAN.INI file unless overwritten by command-line parameters.

Domain names in the wki1_oth_domains member of the WKSTA_USER_INFO_1101 structure are separated by spaces. An empty list is valid. A null pointer means to leave the member unmodified. The wki1_oth_domains member cannot be set with MS-DOS. When setting this element, NetWkstaSetInfo rejects the request if the name list was invalid or if a name could not be added to one or more of the network adapters managed by Net.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaGetInfo


NetWkstaTransportAdd

The NetWkstaTransportAdd function binds (or connects) the redirector to the transport. The redirector is the software on the client computer which generates file requests to the server computer.

Security Requirements

Only members of the Administrators local group can successfully execute NetWkstaTransportAdd.

NET_API_STATUS NetWkstaTransportAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to set the level of information provided.
Value | Meaning
0 | The buf parameter points to a WKSTA_TRANSPORT_INFO_0 structure.

buf
Pointer to an address containing the server transport information structure.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaTransportDel


NetWkstaTransportDel

The NetWkstaTransportDel function unbinds the transport protocol from the redirector, which is the software on the client computer which generates file requests to the server computer.

Security Requirements

Only members of the Administrators local group can successfully execute NetWkstaTransportDel.

NET_API_STATUS NetWkstaTransportDel(
  LPWSTR servername,
  LPWSTR transportname,
  DWORD ucond
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
transportname
Pointer to a Unicode string containing the name of the transport from which to unbind.
ucond
Force level to delete connections on the transport binding.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.
NERR_UseNotFound | The network connection does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaTransportAdd


NetWkstaTransportEnum

The NetWkstaTransportEnum function supplies information about transport protocols that are managed by the redirector, which is the software on the client computer that generates file requests to the server computer.

Security Requirements

No special group membership is required to successfully execute NetWkstaTransportEnum.

NET_API_STATUS NetWkstaTransportEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Ppointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies the following value to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to a WKSTA_TRANSPORT_INFO_0 structure.

bufptr
On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumehandle
Pointer to a DWORD that contains resumehandle, which is used to continue an existing workstation transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_MORE_DATA | Additional information is available.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaTransportAdd, NetWkstaTransportDel


NetWkstaUserEnum

The NetWkstaUserEnum function lists information about all users currently logged on to the workstation. This list includes interactive, service and batch logons.

Security Requirements

Only members of the Administrators local group can successfully execute NetWkstaUserEnum both locally and on a remote server.

NET_API_STATUS NetWkstaUserEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
Pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to a WKSTA_USER_INFO_0 structure.
1 | The bufptr parameter points to a WKSTA_USER_INFO_1 structure.

bufptr
On return, a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen
Preferred maximum length, in 8-bit bytes of returned data.
entriesread
Pointer to a DWORD that contains the actual enumerated element count.
totalentries
Pointer to a DWORD that contains the total number of entries that could have been enumerated from the current resume position.
resumehandle
Pointer to a DWORD that contains resumehandle, whhich is used to continue an existing search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaGetInfo, NetWkstaSetInfo


NetWkstaUserGetInfo

The NetWkstaUserGetInfo function returns information about the currently logged-on user. This function must be called in the context of the logged-on user.

Security Requirements

This function only works locally.

NET_API_STATUS NetWkstaUserGetInfo(
  LPWSTR reserved,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

reserved
This parameter must be set to NULL.
level
Specifies one of the following values to return the level of information provided.
Value | Meaning
0 | The bufptr parameter points to a WKSTA_USER_INFO_0 structure.
1 | The bufptr parameter points to a WKSTA_USER_INFO_1 structure.
1101 | The bufptr parameter points to a WKSTA_USER_INFO_1101 structure.

bufptr
On return, a pointer to the return information structure is returned in the address pointed to by bufptr.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | The system ran out of memory resources. Either the network manager configuration is incorrect, or the program is running on a system with insufficient memory.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaSetInfo


NetWkstaUserSetInfo

The NetWkstaUserSetInfo function sets the user-specific information about the configuration elements for a workstation.

Security Requirements

This function only works locally.

NET_API_STATUS NetWkstaUserSetInfo(
  LPWSTR reserved,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

reserved
This parameter must be set to zero.
level
Specifies one of the following values to set the level of information provided.
Value | Meaning
0 | The buf parameter points to a WKSTA_USER_INFO_0 structure.
1 | The buf parameter points to a WKSTA_USER_INFO_1 structure.
1101 | The buf parameter points to a WKSTA_USER_INFO_1101 structure.

buf
On return a pointer to the return information structure is returned in the address pointed to by buf.
parm_err
Optional pointer to a DWORD that contains the index of the first parameter that causes ERROR_INVALID_PARAMETER. If NULL, the parameter is not returned on error.

Return Values

If the function is successful, it returns NERR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.
Import Library: Use netapi32.lib.

See Also

Networking (Net) Overview, Net Functions, NetWkstaUserGetInfo


Net Structures

The Net structures consist of Alert, Distributed File System, File, Get, Group, Handle Local Group, Message, Replicator, Remote Utility, Schedule, Server, Session, Share, Statistics, User, and Workstation structure groups.

Alert Structures

STD_ALERT
ADMIN_OTHER_INFO
ERRLOG_OTHER_INFO
PRINT_OTHER_INFO
USER_OTHER_INFO

Directory Service Structure

DOMAIN_CONTROLLER_INFO

Distributed File System (Dfs) Structures

DFS_INFO_1
DFS_INFO_2
DFS_INFO_3
DFS_INFO_100
DFS_STORAGE_INFO

File Structures

FILE_INFO_2
FILE_INFO_3

Get Structures

NETCONNECTINFOSTRUCT
NET_DISPLAY_GROUP
NET_DISPLAY_MACHINE
NET_DISPLAY_USER

Group Structures

GROUP_INFO_0
GROUP_INFO_1
GROUP_INFO_2
GROUP_INFO_1002
GROUP_INFO_1005
GROUP_USERS_INFO_0
GROUP_USERS_INFO_1

Handle Structure

HANDLE_INFO_1

Local Group Structures

LOCALGROUP_INFO_0
LOCALGROUP_INFO_1
LOCALGROUP_INFO_1002
LOCALGROUP_MEMBERS_INFO_0
LOCALGROUP_MEMBERS_INFO_1
LOCALGROUP_MEMBERS_INFO_2
LOCALGROUP_MEMBERS_INFO_3
LOCALGROUP_USERS_INFO_0

Message Structures

MSG_INFO_0
MSG_INFO_1

Remote Utility Structure

TIME_OF_DAY_INFO

Replicator Structures

REPL_EDIR_INFO_0
REPL_EDIR_INFO_1
REPL_EDIR_INFO_2
REPL_EDIR_INFO_1000
REPL_EDIR_INFO_1001
REPL_IDIR_INFO_0
REPL_IDIR_INFO_1
REPL_INFO_0
REPL_INFO_1000
REPL_INFO_1001
REPL_INFO_1002
REPL_INFO_1003

Schedule Structures

AT_ENUM
AT_INFO

Server Structures

SERVER_INFO_100
SERVER_INFO_101
SERVER_INFO_102
SERVER_INFO_402
SERVER_INFO_403
SERVER_INFO_502
SERVER_INFO_503
SERVER_INFO_1005
SERVER_INFO_1010
SERVER_INFO_1016
SERVER_INFO_1017
SERVER_INFO_1018
SERVER_INFO_1107
SERVER_INFO_1501
SERVER_INFO_1502
SERVER_INFO_1503
SERVER_INFO_1506
SERVER_INFO_1509
SERVER_INFO_1510
SERVER_INFO_1511
SERVER_INFO_1512
SERVER_INFO_1513
SERVER_INFO_1515
SERVER_INFO_1516
SERVER_INFO_1518
SERVER_INFO_1523
SERVER_INFO_1528
SERVER_INFO_1529
SERVER_INFO_1530
SERVER_INFO_1533
SERVER_INFO_1534
SERVER_INFO_1535
SERVER_INFO_1536
SERVER_INFO_1538
SERVER_INFO_1539
SERVER_INFO_1540
SERVER_INFO_1541
SERVER_INFO_1542
SERVER_INFO_1544
SERVER_INFO_1550
SERVER_INFO_1552
SERVER_TRANSPORT_INFO_0

Session Structures

SESSION_INFO_0
SESSION_INFO_1
SESSION_INFO_2
SESSION_INFO_10
SESSION_INFO_502

Share Structures

SHARE_INFO_0
SHARE_INFO_1
SHARE_INFO_2
SHARE_INFO_502
SHARE_INFO_501
SHARE_INFO_1004
SHARE_INFO_1006
SHARE_INFO_1501

Statistics Structure

STAT_SERVER_0
STAT_WORKSTATION_0

User Structures

USER_INFO_0
USER_INFO_1
USER_INFO_2
USER_INFO_3
USER_INFO_10
USER_INFO_11
USER_INFO_20
USER_INFO_21
USER_INFO_22
USER_INFO_1003
USER_INFO_1005
USER_INFO_1006
USER_INFO_1007
USER_INFO_1008
USER_INFO_1009
USER_INFO_1010
USER_INFO_1011
USER_INFO_1012
USER_INFO_1013
USER_INFO_1014
USER_INFO_1017
USER_INFO_1018
USER_INFO_1020
USER_INFO_1023
USER_INFO_1024
USER_INFO_1025
USER_INFO_1051
USER_INFO_1052
USER_INFO_1053
USER_MODALS_INFO_0
USER_MODALS_INFO_1
USER_MODALS_INFO_2
USER_MODALS_INFO_3
USER_MODALS_INFO_1001
USER_MODALS_INFO_1002
USER_MODALS_INFO_1003
USER_MODALS_INFO_1004
USER_MODALS_INFO_1005
USER_MODALS_INFO_1006
USER_MODALS_INFO_1007

Workstation and Workstation User Structures

WKSTA_INFO_100
WKSTA_INFO_101
WKSTA_INFO_102
WKSTA_INFO_302
WKSTA_INFO_402
WKSTA_TRANSPORT_INFO_0
WKSTA_USER_INFO_0
WKSTA_USER_INFO_1
WKSTA_USER_INFO_1101

Obsolete Structures

AUDIT_ENTRY
CONFIG_INFO_0
CONNECTION_INFO_0
CONNECTION_INFO_1
SERVICE_INFO_0
SERVICE_INFO_1
SERVICE_INFO_2
USE_INFO_0
USE_INFO_1
USE_INFO_2


ADMIN_OTHER_INFO

The ADMIN_OTHER_INFO structure contains error code information in administration messages.

typedef struct _ADMIN_OTHER_INFO {
    DWORD  alrtad_errcode;
    DWORD  alrtad_numstrings;
}ADMIN_OTHER_INFO, *PADMIN_OTHER_INFO, *LPADMIN_OTHER_INFO;

Members

alrtad_errcode
Specifies the error code for the new message in the administration message.
alrtad_numstrings
Specifies the number (0-9) of consecutive Unicode strings in the administration message.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.

See Also

Networking (Net) Overview, Net Structures, NetAlertRaise


AT_ENUM

The AT_ENUM structure enumerates and returns information about an entire queue of jobs that have already been submitted.

typedef struct _AT_ENUM {
    DWORD   JobId;
    DWORD   JobTime;
    DWORD   DaysOfMonth;
    UCHAR   DaysOfWeek;
    UCHAR   Flags;
    LPWSTR  Command;
} AT_ENUM, *PAT_ENUM, *LPAT_ENUM;

Members

JobID
Job identifier of an already submitted job.
JobTime
Time of day at which a job is scheduled to run. Time is a local time at a computer on which the Schedule service is running. Time is measured from midnight and is expressed in milliseconds.
DaysOfMonth
Bitmask for the days of the month on which a job is scheduled to run. The bitmask is NULL if a job was scheduled to run only once at the first occurrence of JobTime. For each bit that is set in the bitmask a job will run at JobTime on a corresponding day of the month. Bit 0 corresponds to first day of the month, and so on.
DaysOfWeek
Bitmask for the days of the week on which this job is scheduled to run. The bitmask is NULL if a job was scheduled to run only once at the first occurrence of JobTime. For each bit that is set in the bitmask a job will run at JobTime on a corresponding day of the week. Bit 0 corresponds to Monday (first day of the week), and so on.
Flags
Bitmask describing job properties. For job submission (NetScheduleJobAdd), possible values are:
JOB_RUN_PERIODICALLY
If this flag bit is set, the job runs on every day for which corresponding bits in DaysOfMonth or DaysOfWeek are set. If this flag bit is clear, the job runs only once for each bit that was set in DaysOfMonth or DaysOfWeek at the time of job submission.
JOB_ADD_CURRENT_DATE
When this flag bit is set, the job will also execute at the first occurrence of JobTime at the computer to which the job is submitted. In other words, setting this flag bit is equivalent to setting the corresponding day bit in the DaysOfMonth bitmask.

For job information retrieval (NetScheduleJobEnum and NetScheduleJobGetInfo), possible values are:

JOB_RUN_PERIODICALLY
This flag bit is equal to the original value of this flag bit when a job was submitted.
JOB_EXEC_ERROR
This flag bit is set whenever the Schedule service failed to execute successfully this job the last time this job was supposed to run.
JOB_RUNS_TODAY
This flag bit is set if JobId is larger than the current time of day at the computer at which this job is queued.
Command
Pointer to a Unicode string that contains the name of the command, batch program, or binary file to execute.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.

See Also

Networking (Net) Overview, Net Structures, NetScheduleJobEnum


AT_INFO

The AT_INFO structure specifies jobs to be added or scheduled and returns information about a job that has already been submitted.

typedef struct _AT_INFO {
    DWORD   JobTime;
    DWORD   DaysOfMonth;
    UCHAR   DaysOfWeek;
    UCHAR   Flags;
    LPWSTR  Command;
} AT_INFO, *PAT_INFO, *LPAT_INFO;

Members

JobTime
Time of day at which a job is scheduled to run. Time is a local time at a computer on which the Schedule service is running. Time is measured from midnight and is expressed in milliseconds.
DaysOfMonth
Bitmask for the days of the month on which a job is scheduled to run. The bitmask is NULL if a job was scheduled to run only once at the first occurrence of JobTime. For each bit that is set in the bitmask a job will run at JobTime on a corresponding day of the month. Bit 0 corresponds to the first day of the month, and so on.
DaysOfWeek
Bitmask for the days of the week on which the job is scheduled to run. The bitmask is NULL if a job was scheduled to run only once at the first occurrence of JobTime. For each bit that is set in the bitmask a job will run at JobTime on a corresponding day of the week. Bit 0 corresponds to Monday (first day of the week), and so on.
Flags
Bitmask describing job properties. For job submission (NetScheduleJobAdd), the possible values are:
JOB_RUN_PERIODICALLY
If this flag bit is set, the job runs on every day for which corresponding bits in DaysOfMonth or DaysOfWeek are set. If this flag bit is clear, then job runs only once for each bit that was set in DaysOfMonth or DaysOfWeek at the time of job submission.
JOB_ADD_CURRENT_DATE
When this flag bit is set, the job will also execute at the first occurrence of JobTime at the computer to which the job is submitted. In other words, setting this flag bit is equivalent to setting the corresponding day bit in the DaysOfMonth bitmask.

For job information retrieval (NetScheduleJobEnum and NetScheduleJobGetInfo), possible values are:

JOB_RUN_PERIODICALLY
This flag bit is equal to the original value of this flag bit when a job was submitted.
JOB_EXEC_ERROR
This flag bit is set whenever Schedule service failed to successfully execute this job the last time it was supposed to run.
JOB_RUNS_TODAY
This flag bit is set if JobId is larger than the current time of day at the computer at which this job is queued.
Command
Pointer to a Unicode string that contains the name of the command, batch program, or binary file to execute.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmat.h.

See Also

Networking (Net) Overview, Net Structures, NetScheduleJobAdd, NetScheduleJobGetInfo


AUDIT_ENTRY

The AUDIT_ENTRY structure contains audit entry information about specified servers.

typedef struct _AUDIT_ENTRY {
     DWORD          ae_len;
     DWORD          ae_reserved;
     DWORD          ae_time;
     DWORD          ae_type;
     DWORD          ae_data_offset;
     DWORD          ae_data_size;
} AUDIT_ENTRY, *PAUDIT_ENTRY, *LPAUDIT_ENTRY;

Members

ae_len
Specifies the length of the audit entry. Both have the same value. This element is included at the beginning and at the end of the audit entry to enable both backward and forward scanning of the log.
ae_reserved
Reserved.
ae_time
Specifies when the audit entry was generated. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.
ae_type
Specifies the type of audit entry. Type values from 0x0000 through 0x07FF are reserved. OEMs and other application programmers can reserve values from 0x0800 through 0xFFFF.
ae_data_offset
Specifies the byte offset from the beginning of the audit entry to the beginning of the variable-length portion (ae_data) of the audit entry.
ae_data_size
Specifies the variable-length portion of the audit entry; it differs depending on the type of entry specified by ae_type. The information begins at ae_data_offset bytes from the top of the audit entry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaudit.h.

See Also

Networking (Net) Overview, Net Structures, NetAuditRead


CONFIG_INFO_0

The CONFIG_INFO_0 structure specifies name strings and values to configure components on local computers.

typedef struct _CONFIG_INFO_0 {
     LPTSTR         cfgi0_key;
     LPTSTR         cfgi0_data;
} CONFIG_INFO_0, *PCONFIG_INFO_0, *LPCONFIG_INFO_0;
cfgi0_key
Specifies a string with a configuration entry name. The name represents an entry into the LANMAN.INI file.
cfgi0_data
Specifies values that a user assigns to the configuration entry name.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmconfig.h.

See Also

Networking (Net) Overview, Net Structures, NetConfigSet, NetConnectionEnum


CONNECTION_INFO_0

The CONNECTION_INFO_0 structure specifies the identification number of a connection.

typedef struct _CONNECTION_INFO_0 {
    DWORD    coni0_id;
} CONNECTION_INFO_0, *PCONNECTION_INFO_0, *LPCONNECTION_INFO_0;

Members

coni0_id
Connection identification number.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetConnectionEnum


CONNECTION_INFO_1

The CONNECTION_INFO_0 structure specifies the identification number of a connection, number of open files, connection time, number of users on the connection, and the type of connection.

typedef struct _CONNECTION_INFO_1 {
    DWORD     coni1_id;
    DWORD     coni1_type;
    DWORD     coni1_num_opens;
    DWORD     coni1_num_users;
    DWORD     coni1_time;
    LPTSTR    coni1_username;
    LPTSTR    coni1_netname;
} CONNECTION_INFO_1, *PCONNECTION_INFO_1, *LPCONNECTION_INFO_1;

Members

coni1_id
Connection identification number.
coni1_type
Indicates the type of connection made from the local device name to the shared resource. This member can be one of the following values:
Value | Meaning
STYPE_DISKTREE | Print queue
STYPE_PRINTQ | Disk drive
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess Communication (IPC)

coni1_num_opens
Indicates the number of files currently open as a result of the connection.
coni1_num_users
Indicates the number of users are on the connection.
coni1_time
Indicates the number of seconds the connection has been established.
coni1_username
Points to a Unicode string. If the server sharing the resource is running with user-level security, the coni1_username member describes which user made the connection. If the server is running with share-level security, coni1_username describes which computer (computername) made the connection.
coni1_netname
Points to a Unicode string specifying either the sharename of the server's shared resource or the computername of the client. The value of this member depends on which name was specified as the pszQualifier parameter of the NetConnectionEnum function. The name not specified in the pszQualifier parameter of the NetConnectionEnum function is automatically supplied to the pszQualifier of coni1_netname.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetConnectionEnum


DFS_INFO_1

The DFS_INFO_1 structure contains the name of a junction point in a Distributed File System (Dfs) tree structure.

typedef struct _DFS_INFO_1 {
    LPWSTR  EntryPath;  // Dfs name for the top of the junction point
} DFS_INFO_1, *PDFS_INFO_1, *LPDFS_INFO_1;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string will be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

Remarks

The Dfs functions use the DFS_INFO_1 structure to retrieve information about a Dfs junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.

See Also

Networking (Net) Overview, Net Structures, NetDfsEnum, NetDfsGetInfo


DFS_INFO_2

The DFS_INFO_2 structure contains information about a junction point in a Distributed File System (Dfs) tree structure. The information includes Dfs name, status, and the number of alternate paths associated with the junction point.

typedef struct _DFS_INFO_2 {
    LPWSTR  EntryPath;    // Dfs name for the top of the junction point
    LPWSTR  Comment;      // comment for the junction point
    DWORD   State;        // state of the junction point
    DWORD   NumberOfStorages; // number of storage shares for the junction point
} DFS_INFO_2, *PDFS_INFO_2, *LPDFS_INFO_2;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string will be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

Comment
Pointer to a null-terminated Unicode character string that contains a comment associated with the junction point.
State
A set of bit flags that specify the status of the junction point. This member must be one of the following values.
Value | Meaning
DFS_VOLUME_STATE_OK | The specified junction point is in the normal state.
DFS_VOLUME_STATE_INCONSISTENT | The internal Dfs database is inconsistent with the specified junction point. Attempts to repair the inconsistency have failed.
DFS_VOLUME_STATE_OFFLINE | The specified junction point is offline or unavailable.
DFS_VOLUME_STATE_ONLINE | The specified junction point is available.

NumberOfStorages
Specifies the number of alternate paths, that is, the number of shares, associated with the junction point.

Remarks

The Dfs functions use the DFS_INFO_2 structure to retrieve information about a Dfs junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.

See Also

Networking (Net) Overview, Net Structures, NetDfsEnum, NetDfsGetInfo


DFS_INFO_3

The DFS_INFO_3 structure contains detailed information about a junction point in a Distributed File System (Dfs) tree structure. The information includes Dfs name, status, and the path for each alternate path associated with the junction point.

typedef struct _DFS_INFO_3 {
    LPWSTR  EntryPath;     //Dfs name for the top of the junction point
    LPWSTR  Comment;       //comment for the junction point
    DWORD   State;         //state of the junction point
    DWORD   NumberOfStorages; //number of storage servers for the junction point
#ifdef MIDL_PASS
    [size_is(NumberOfStorages)] LPDFS_STORAGE_INFO Storage;
#else
    LPDFS_STORAGE_INFO Storage; //an array (of NumberOfStorages elements) of storage-specific information.
#endif // MIDL_PASS
} DFS_INFO_3, *PDFS_INFO_3, *LPDFS_INFO_3;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a junction point in a Dfs tree structure. The string will be of the form:

\\Dfsname\sharename\path-to-junction-point

where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the path on the physical share.

Comment
Pointer to a null-terminated Unicode character string that contains a comment associated with the junction point.
State
A set of bit flags that specify the status of the junction point. This member must be one of the following values.
Value | Meaning
DFS_VOLUME_STATE_OK | The specified junction point is in the normal state.
DFS_VOLUME_STATE_INCONSISTENT | The internal Dfs database is inconsistent with the specified junction point. Attempts to repair the inconsistency have failed.
DFS_VOLUME_STATE_OFFLINE | The specified junction point is offline or unavailable.
DFS_VOLUME_STATE_ONLINE | The specified junction point is available.

NumberOfStorages
Specifies the number of alternate paths, that is, the number of shares, associated with the junction point.
Storage
Pointer to an array of DFS_STORAGE_INFO structures. The NumberOfStorages member specifies the number of structures in the array.

Remarks

A DFS_INFO_3 structure contains one or more DFS_STORAGE_INFO structures, one for each alternate path specified for the Dfs junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.

See Also

Networking (Net) Overview, Net Structures, DFS_STORAGE_INFO, NetDfsEnum, NetDfsGetInfo


DFS_INFO_100

The DFS_INFO_100 structure contains a comment associated with a junction point in a Distributed File System (Dfs) tree structure.

typedef struct _DFS_INFO_100 {
    LPWSTR  Comment;        // comment for the junction point
} DFS_INFO_100, *PDFS_INFO_100, *LPDFS_INFO_100;

Members

Comment
Pointer to a null-terminated Unicode character string that contains the comment associated with the specified junction point.

Remarks

The Dfs functions use the DFS_INFO_100 structure to retrieve information about a Dfs junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.

See Also

Networking (Net) Overview, Net Structures, NetDfsGetInfo, NetDfsSetInfo


DFS_STORAGE_INFO

The DFS_STORAGE_INFO structure contains the status of a share referenced by a junction point in a Distributed File System (Dfs) tree structure.

typedef struct _DFS_STORAGE_INFO {
    ULONG   State;         // state of the storage
    LPWSTR  ServerName;    // name of server exporting the storage
    LPWSTR  ShareName;     // name of share exporting the storage
} DFS_STORAGE_INFO, *PDFS_STORAGE_INFO, *LPDFS_STORAGE_INFO;

Members

State
A set of bit flags that specify the status of the storage server. This member must be one of the following values.
Value | Meaning
DFS_STORAGE_STATE_OFFLINE | The specified computer is offline or unavailable.
DFS_STORAGE_STATE_ONLINE | The specified computer is available.

ServerName
Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references.
ShareName
Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references.

Remarks

A DFS_INFO_3 structure contains one or more DFS_STORAGE_INFO structures, one for each alternate path specified for the Dfs junction point.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmdfs.h.

See Also

Networking (Net) Overview, Net Structures, DFS_INFO_3, NetDfsEnum, NetDfsGetInfo


DOMAIN_CONTROLLER_INFO

[This is preliminary documentation and subject to change.]

The DOMAIN_CONTROLLER_INFO structure contains information that affects properties of the domain controller (DC).

typedef struct _DOMAIN_CONTROLLER_INFO {
    LPTSTR DomainControllerName;
    LPTSTR DomainControllerAddress;
    ULONG DomainControllerAddressType;
    GUID DomainGuid;
    LPTSTR DomainName;
    LPTSTR TreeName;
    ULONG Flags;
    LPTSTR DcSiteName;
    LPTSTR ClientSiteName;
} DOMAIN_CONTROLLER_INFO, *PDOMAIN_CONTROLLER_INFO;

Members

DomainControllerName
Pointer to a null-terminated Unicode string specifying the computer name of the discovered domain controller. The returned computer name is prefixed with \\. The DNS-style name (for example, \\phoenix.microsoft.com.) will be returned if available. If a DNS-style name is returned, it will be terminated with a period, indicating that the returned name is an absolute (non-relative) DNS name. If the DNS-style name is not available, the flat-style name (for example, \\phoenix) will be returned. This example would apply if the domain is a Windows NT 4.0 domain or if the domain does not support the IP family of protocols.
DomainControllerAddress
Pointer to a zero-terminated Unicode string specifying the address of the discovered domain controller. The address is prefixed with \\ to aid in passing it as the ComputerName parameter in the Directory Service (DS) functions to various subsequent functions. This string will be one of the types defined by DomainControllerAddressType.
DomainControllerAddressType
Indicates the type of address specified in DomainControllerAddress. The following valid values are presented in order, in case multiple forms are known.
Value | Meaning
DS_INET_ADDRESS | Address is a string IP address (for example, \\157.55.94.74) of the domain controller.
DS_NETBIOS_ADDRESS | The NetBIOS name (for example, \\phoenix) of the domain controller.

DomainGuid
The GUID of the domain. This member will be zero if the DC does not have a Domain GUID (for example, the DC is not a Windows NT 5 DC).
DomainName
Pointer to a zero-terminated Unicode string specifying the name of the domain. The DNS-style name (for example, microsoft.com.) will be returned if available. Otherwise, the flat-style name (for example, microsoft) will be returned. This name may be different than the requested domain name if the domain has been renamed. If a DNS-style name is returned, it will be terminated by a period, indicating that the returned name is an absolute (non-relative) DNS name.
TreeName
Pointer to a zero-terminated Unicode string specifying the name of the domain at the root of the DS tree. The DNS-style name (for example, microsoft.com.) will be returned if available. Otherwise, the flat-style name (for example, microsoft) will be returned. If a DNS-style name is returned, it will be terminated be a period indicating that the returned name is an absolute (non-relative) DNS name.
Flags
The following flags describe the domain controller.
Value | Meaning
DS_PDC_FLAG | Domain controller is the PDC of the domain.
DS_WRITABLE_FLAG | Domain controller hosts a writable DS (or SAM).
DS_FDC_FLAG | Domain controller is the FDC of the domain.
DS_GC_FLAG | Domain controller is a GC server for TreeName.
DS_DS_FLAG | Domain controller is a directory service server for the domain.
DS_KDC_FLAG | Domain controller is a Kerberos Key Distribution Center for the domain.
DS_TIMESERV_FLAG | Domain controller is running the Windows Time service for the domain.
DS_DNS_CONTROLLER_FLAG | DomainControllerName is in DNS format.
DS_DNS_DOMAIN_FLAG | DomainName is in DNS format.
DS_DNS_TREE_FLAG | TreeName is in DNS format.

DcSiteName
The name of the site where the domain controller is located. This value may be NULL if the DC is not in a site (for example, the DC is a Windows NT 4.0 DC).
ClientSiteName
The name of the site where the DC is configured to be in. This value may be NULL if the site that the computer named by ComputerName cannot be found (for example, if the DS administrator has not associated the subnet that the computer is in with a valid site).

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in dsgetdc.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Networking (Net) Overview, Net Structures


ERRLOG_OTHER_INFO

The ERRLOG_OTHER_INFO structure contains error log information.

type struct _ERRLOG_OTHER_INFO {
    DWORD  alrter_errcode;
    DWORD  alrter_offset;
}ERRLOG_OTHER_INFO, *PERRLOG_OTHER_INFO, *LPERRLOG_OTHER_INFO;

Members

alrter_errcode
Specifies the error code that was written to the error log.
alrter_offset
Specifies the offset for the new entry in the errorlog.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.

See Also

Networking (Net) Overview, Net Structures, NetAlertRaise


FILE_INFO_2

The FILE_INFO_2 structure specifies an identification number to a file, device, or pipe.

typedef struct _FILE_INFO_2 {
    DWORD    fi2_id;
} FILE_INFO_2, *PFILE_INFO_2, *LPFILE_INFO_2;

Members

fi2_id
Specifies the identification number assigned to the resource when it is opened.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetFileEnum, NetFileGetInfo


FILE_INFO_3

The FILE_INFO_3 structure specifies pertinent information about files, devices, and pipes.

typedef struct _FILE_INFO_3 {
    DWORD     fi3_id;
    DWORD     fi3_permissions;
    DWORD     fi3_num_locks;
    LPWSTR    fi3_pathname;
    LPWSTR    fi3_username;
} FILE_INFO_3, *PFILE_INFO_3, *LPFILE_INFO_3;

Members

fi3_id
Specifies the identification number assigned to the resource when it is opened.
fi3_permissions
Specifies the access permissions of the opening application. This member can be any of the following values:
Value | Meaning
PERM_FILE_READ | Permission to read a resource and, by default, execute the resource.
PERM_FILE_WRITE | Permission to write to a resource.
PERM_FILE_CREATE | Permission to create a resource; data can be written when creating the resource.

fi3_num_locks
Specifies the number of file locks on the file, device, or pipe.
fi3_pathname
Points to a Unicode string that gives the path of the opened resource.
fi3_username
Points to a Unicode string that specifies which user (on servers that have user-level security) or which computer (on servers that have share-level security) opened the resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetFileEnum, NetFileGetInfo


GROUP_INFO_0

The GROUP_INFO_0 structure renames the global group and specifies information about the group, including identifier and resource attributes.

typedef struct _GROUP_INFO_0 {
    LPWSTR   grpi0_name;
}GROUP_INFO_0, *PGROUP_INFO_0, *LPGROUP_INFO_0;

Members

grpi0_name
A Unicode string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string. For NetGroupSetInfo, this member specifies the new name of the global group.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo


GROUP_INFO_1

The GROUP_INFO_1 structure specifies information about a global group, including name, identifier, and resource attributes.

typedef struct _GROUP_INFO_1 {
    LPWSTR   grpi1_name;
    LPWSTR   grpi1_comment;
}GROUP_INFO_1, *PGROUP_INFO_1, *LPGROUP_INFO_1;

Members

grpi1_name
A Unicode string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string. For NetGroupSetInfo, this member is ignored.
grpi1_comment
A Unicode string that contains a remark for the group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo


GROUP_INFO_2

The GROUP_INFO_2 structure specifies information about a global group, including name, identifier, and resource attributes.

typedef struct _GROUP_INFO_2 {
    LPWSTR   grpi2_name;
    LPWSTR   grpi2_comment;
    DWORD    grpi2_group_id;
    DWORD    grpi2_attributes;
}GROUP_INFO_2, *PGROUP_INFO_2;

Members

grpi2_name
A Unicode string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string. For NetGroupSetInfo, this member is ignored.
grpi2_comment
A Unicode string that contains a remark for the group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ characters.
grpi2_group_id
The relative identifier of this account.
grpi2_attributes
The attributes of a group (stored in TOKEN_GROUPS). For Windows NT 4.0, you can no longer set these attributes. They are hardwired to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, SE_GROUP_ENABLED_BY_DEFAULT:
Value | Meaning
SE_GROUP_ENABLED_BY_DEFAULT | Indicates that the group is enabled by default. Use this value to specify the initial state of the group.
SE_GROUP_MANDATORY | Indicates that the user may not disable the group. Disabling a group causes the group membership to be ignored by the access validation routines.
SE_GROUP_OWNER | Indicates that the group can be assigned as the owner of an object.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo


GROUP_INFO_1002

The GROUP_INFO_1002 structure specifies information about a group, including name, identifier, and resource attributes.

typedef struct _GROUP_INFO_1002 {
     LPWSTR  grpi1002_comment;
} GROUP_INFO_1002, *PGROUP_INFO_1002, *LPGROUP_INFO_1002;

Members

grpi1002_comment
A Unicode string that contains a remark for the group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupSetInfo


GROUP_INFO_1005

The GROUP_INFO_1005 structure specifies information about a group, including name, identifier, and resource attributes.

typedef struct _GROUP_INFO_1005 {
     DWORD  grpi1005_attributes;
} GROUP_INFO_1005, *PGROUP_INFO_1005, *LPGROUP_INFO_1005;

Members

grpi1005_attributes
The attributes of a group (stored in TOKEN_GROUPS). For Windows NT 4.0, you can no longer set these attributes. They are hardwired to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, SE_GROUP_ENABLED_BY_DEFAULT.
Value | Meaning
SE_GROUP_ENABLED_BY_DEFAULT | Indicates that the group is enabled by default. Use this value to specify the initial state of the group
SE_GROUP_MANDATORY | Indicates that the user may not disable the group. Disabling a group causes the group membership to be ignored by the access validation routines.
SE_GROUP_OWNER | Indicates that the group can be assigned as the owner of an object.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupSetInfo


GROUP_USERS_INFO_0

The GROUP_USERS_INFO_0 structure specifies information about the user of a group, and resource attributes.

typedef struct _GROUP_USERS_INFO_0 {
     LPWSTR  grui0_name;
} GROUP_USERS_INFO_0, *PGROUP_USERS_INFO_0, *LPGROUP_USERS_INFO_0;

Members

grui0_name
A Unicode string that specifies the group to which a user belongs. The constant GNLEN specifies the maximum number of characters in the string.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupGetUsers, NetGroupSetUsers, NetUserGetGroups, NetUserGetInfo, NetUserSetGroups


GROUP_USERS_INFO_1

The GROUP_USERS_INFO_1 structure specifies information about the user of a group, and resource attributes.

typedef struct _GROUP_USERS_INFO_1 {
     LPWSTR  grui1_name;
     DWORD   grui1_attributes;
} GROUP_USERS_INFO_1, *PGROUP_USERS_INFO_1, *LPGROUP_USERS_INFO_1;

Members

grui1_name
A Unicode string that specifies the group to which a user belongs. The constant GNLEN specifies the maximum number of characters in the string.
grui1_attributes
The attributes of a group (stored in TOKEN_GROUPS). For Windows NT 4.0, you can no longer set these attributes. They are hardwired to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, SE_GROUP_ENABLED_BY_DEFAULT.
Value | Meaning
SE_GROUP_ENABLED_BY_DEFAULT | Indicates that the group is enabled by default. Use this value to specify the initial state of the group.
SE_GROUP_MANDATORY | Indicates that the user may not disable the group. Disabling a group causes the group membership to be ignored by the access validation routines.
SE_GROUP_OWNER | Indicates that the group can be assigned as the owner of an object.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetGroupGetUsers, NetGroupSetUsers, NetUserGetGroups, NetUserGetInfo, NetUserSetGroups


HANDLE_INFO_1

The HANDLE_INFO_1 structure specifies the number of data bytes and how long it takes to send the data.

typedef struct _HANDLE_INFO_1 {
    DWORD   hdli1_chartime;
    DWORD   hdli1_charcount;
}HANDLE_INFO_1, *PHANDLE_INFO_1, *LPHANDLE_INFO_1;

Members

hdli1_chartime
Specifies, in milliseconds, the amount of time the workstation collects data to send to a character device or named pipe.
hdli1_charcount
Specifies, in bytes, the number of characters the workstation stores before it sends data to a character device or named pipe.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmchdev.h.

See Also

Networking (Net) Overview, Net Structures, NetHandleGetInfo, NetHandleSetInfo


LOCALGROUP_INFO_0

The LOCALGROUP_INFO_0 structure renames the local group.

typedef struct _LOCALGROUP_INFO_0 {
    LPWSTR   lgrpi0_name;
}LOCALGROUP_INFO_0, *PLOCALGROUP_INFO_0, *LPLOCALGROUP_INFO_0;

Members

lgrpi0_name
A Unicode string that specifies the local group to which a user belongs. The constant GNLEN specifies the maximum number of characters in the string. For the NetLocalGroupSetInfo function, this member specifies the new name of the local group.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetLocalGroupAdd, NetLocalGroupEnum, NetLocalGroupGetInfo, NetLocalGroupSetInfo


LOCALGROUP_INFO_1

The LOCALGROUP_INFO_1 structure renames the local group and specifies a comment describing the local group.

typedef struct _LOCALGROUP_INFO_1 {
    LPWSTR   lgrpi1_name;
    LPWSTR   lgrpi1_comment;
}LOCALGROUP_INFO_1, *PLOCALGROUP_INFO_1, *LPLOCALGROUP_INFO_1;

Members

lgrpi1_name
A Unicode string that specifies the local group to which a user belongs. The constant GNLEN specifies the maximum number of characters in the string. For the NetLocalGroupSetInfo function, this member is ignored
lgrpi1_comment
A Unicode string that points to a Unicode string that contains a remark for the local group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetLocalGroupAdd, NetLocalGroupEnum, NetLocalGroupGetInfo, NetLocalGroupSetInfo


LOCALGROUP_INFO_1002

The LOCALGROUP_INFO_1002 structure specifies the name of the local group and a comment describing the local group.

typedef struct _LOCALGROUP_INFO_1002 {
     LPWSTR  lgrpi1002_comment;
}LOCALGROUP_INFO_1002, *PLOCALGROUP_INFO_1002, *LPLOCALGROUP_INFO_1002;

Members

lgrpi1002_comment
Points to a Unicode string that contains a remark for the local group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetLocalGroupSetInfo


LOCALGROUP_MEMBERS_INFO_0

The LOCALGROUP_MEMBERS_INFO_0 structure is used in the NetLocalGroupAddMembers and NetLocalGroupDelMembers functions to identify a member of a local group.

typedef struct _LOCALGROUP_MEMBERS_INFO_0 {
    PSID  lgrmi0_sid;
} LOCALGROUP_MEMBERS_INFO_0;

Members

lgrmi0_sid
Points to the security identifier of the member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, LOCALGROUP_MEMBERS_INFO_1,
LOCALGROUP_MEMBERS_INFO_2,
LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers, NetLocalGroupSetMembers


LOCALGROUP_MEMBERS_INFO_1

The LOCALGROUP_MEMBERS_INFO_1 structure is used in the NetLocalGroupAddMembers and NetLocalGroupDelMembers functions to identify a member of a local group, and account and security information for the member.

typedef struct _LOCALGROUP_MEMBERS_INFO_1 {
     PSID         lgrmi1_sid;
     SID_NAME_USE lgrmi1_sidusage;
     LPWSTR       lgrmi1_name;
} LOCALGROUP_MEMBERS_INFO_1, *PLOCALGROUP_MEMBERS_INFO_1, *LPLOCALGROUP_MEMBERS_INFO_1;

Members

lgrmi1_sid
Specifies the security identifier of an account that is a member of this local group. The account may be a user account or a global group account.
lgrmi1_sidusage
Specifies the account type of the security identifier specified in the lgrmi1_sid member. The following values are possible.
Value | Meaning
SidTypeUser | The account is a user account.
SidTypeGroup | The account is a global group account.
SidTypeWellKnownGroup | The account is a well-known group account (such as Everyone).
SidTypeDeletedAccount | The account has been deleted.
SidTypeUnknown | The account type cannot be determined.

lgrmi1_name
Specifies one account name of the account specified by the lgrmi1_sid member. The account name does not include the domain name.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_2, LOCALGROUP_MEMBERS_INFO_3,
NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers


LOCALGROUP_MEMBERS_INFO_2

The LOCALGROUP_MEMBERS_INFO_2 structure is used in the NetLocalGroupAddMembers and NetLocalGroupDelMembers functions to identify a member of a local group, and account and security information for the member.

typedef struct _LOCALGROUP_MEMBERS_INFO_2 {
     PSID         lgrmi2_sid;
     SID_NAME_USE lgrmi2_sidusage;
     LPWSTR       lgrmi2_domainandname;
} LOCALGROUP_MEMBERS_INFO_2, *PLOCALGROUP_MEMBERS_INFO_2, *LPLOCALGROUP_MEMBERS_INFO_2;

Members

lgrmi2_sid
Specifies the security identifier of an account that is a member of this local group. The account may be a user account or a global group account.
Lgrmi2_sidusage
Specifies the account type of the security identifier specified in the lgrmi2_sid member. The following values are possible.
Value | Meaning
SidTypeUser | The account is a user account.
SidTypeGroup | The account is a global group account.
SidTypeWellKnownGroup | The account is a well-known group account (such as Everyone).
SidTypeDeletedAccount | The account has been deleted.
SidTypeUnknown | The account type cannot be determined.

lgrmi2_domainandname
Specifies the account name of the account specified by the lgrmi2_sid member. The account name is of the form.
<DomainName>\<AccountName>

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_1, LOCALGROUP_MEMBERS_INFO_3,
NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers


LOCALGROUP_MEMBERS_INFO_3

The LOCALGROUP_MEMBERS_INFO_3 structure is used in the NetLocalGroupAddMembers and NetLocalGroupDelMembers functions to identify a member of a local group.

typedef struct _LOCALGROUP_MEMBERS_INFO_3 {
    LPWSTR  lgrmi3_domainandname;
} LOCALGROUP_MEMBERS_INFO_3;

Members

lgrmi3_domainandname
Points to a null-terminated Unicode string containing the name of the member prefixed by the domain name and the "\" separator character.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_1, LOCALGROUP_MEMBERS_INFO_2,
NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers, NetLocalGroupSetMembers


LOCALGROUP_USERS_INFO_0

The LOCALGROUP_USERS_INFO_0 structure contains user names within a local group.

typedef struct _LOCALGROUP_USERS_INFO_0 {
     LPWSTR  lgrui0_name;
} LOCALGROUP_USERS_INFO_0, *PLOCALGROUP_USERS_INFO_0,
  *LPLOCALGROUP_USERS_INFO_0;

Members

lgrui0_name
Pointer to a Unicode string containing a list of user names in the local group.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserGetLocalGroups


MSG_INFO_0

The MSG_INFO_0 structure specifies a message alias.

typedef struct _MSG_INFO_0 {
    LPWSTR  msgi0_name;
}MSG_INFO_0, *PMSG_INFO_0, *LPMSG_INFO_0;

Members

msgi0_name
Contains a Unicode string that specifies the alias to which the message is to be sent. The constant LEN specifies the maximum number of characters in the string.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.

See Also

Networking (Net) Overview, Net Structures, NetMessageNameEnum, NetMessageNameGetInfo


MSG_INFO_1

The MSG_INFO_1 structure specifies an alias to retrieve a message from or send a message to.

typedef struct _MSG_INFO_1 {
    LPWSTR  msgi1_name;
    DWORD   msgi1_forward_flag;
    LPWSTR  msgi1_forward;
}MSG_INFO_1, *PMSG_INFO_1, *LPMSG_INFO_1;

Members

msgi1_name
Contains a Unicode string that specifies the alias to which the message is to be sent. The constant LEN specifies the maximum number of characters in the string.
msgi1_forward_flag
Contains a Unicode string that specifies the alias to which the message is to be sent. The constant LEN specifies the maximum number of characters in the string.
msgi1_forward
Indicates the number of seconds elapsed since the usri1_password member last changed one of three values specifying the level of privilege assigned the usri1_name member. This member can be one of the following values:
Value | Meaning
MSGNAME_NOT_FORWARDED | Name is not forwarded.
MSGNAME_FORWARDED_TO | Name is forwarded to a remote computer.
MSGNAME_FORWARDED_FROM | Name is forwarded from a remote computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmmsg.h.

See Also

Networking (Net) Overview, Net Structures, NetMessageNameEnum, NetMessageNameGetInfo


NETCONNECTINFOSTRUCT

The NETCONNECTINFOSTRUCT structure contains information about the expected performance of a connection used to access a network resource. In the dwSpeed, dwDelay or dwOptDataSize members, a value of zero means that no information is available. In the dwSpeed or dwDelay member, a value of one means that the actual value is greater than can be represented in the unit.

typedef struct _NETCONNECTINFOSTRUCT{
    DWORD cbStructure;
    DWORD dwFlags;
    DWORD dwSpeed;
    DWORD dwDelay;
    DWORD dwOptDataSize;
} NETCONNECTINFOSTRUCT,  *LPNETCONNECTINFOSTRUCT;

Members

cbStructure
The size, in bytes, of the NETCONNECTINFOSTRUCT structure. This value is supplied by the caller to indicate the size of the structure.
dwFlags
A bit mask. This member can be one or more of the following flags.
Value | Meaning
WNCON_FORNETCARD | If this flag is set, information is being returned for the performance of the network card, in the absence of information about the actual connection. If this flag is not set, information is being returned for the current connection with the resource, with any routing degradation taken into consideration.
WNCON_NOTROUTED | If set, the connection is not being routed. If the flag is not set, the connection may be going through routers that limit performance. Consequently, if WNCON_FORNETCARD is set, actual performance may be much less than the information returned.
WNCON_SLOWLINK | If the flag is set, the connection is over a medium that is typically slow (for example, over a modem using a normal quality phone line). The WNCON_SLOWLINK bit may not be set if the dwSpeed member is set to a non-zero value.
WNCON_DYNAMIC | If the flag is set, some of the information being returned is dynamically recalculated, so reissuing this request may return different or more current information.

dwSpeed
The speed of the media to the network resource in units of 100 bits per second (bps) For example, a 1200 baud point-to-point link returns 12.
dwDelay
The one-way delay introduced by the network when sending information (that is, the time between when data starts being sent and the time that it starts being received), in milliseconds. This delay is additional to any latency that was incorporated into the calculation of dwSpeed, so the value returned will be zero for accessing most resources.
dwOptDataSize
A recommendation for the size of data, in bytes, that is most efficiently sent through the network when an application makes a single request to the network resource. For example, for a disk network resource, this value might be 2048 or 512 when writing a block of data

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.

See Also

Networking (Net) Overview, Net Structures, MultinetGetConnectionPerformance, NetUserAdd


NET_DISPLAY_GROUP

The NET_DISPLAY_GROUP structure contains information that an account manager can access to determine information about user groups.

typedef struct _NET_DISPLAY_GROUP {
    LPWSTR   grpi3_name;
    LPWSTR   grpi3_comment;
    DWORD    grpi3_group_id;
    DWORD    grpi3_attributes;
    DWORD    grpi3_next_index;
} NET_DISPLAY_GROUP, *PNET_DISPLAY_GROUP;

Members

usri3_name
A Unicode string that specifies the name of the group.
usri3_comment
A Unicode string that points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri3_group_id
Specifies the relative identifier of the group. The relative identifier is determined by the accounts database when the group is created. It uniquely defines the group to the account manager within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_attributes
Lists attributes of the defined group. For NT Windows 4.0, you can no longer set these attributes. They are hardwired to SE_GROUP_MANDATORY,| SE_GROUP_ENABLED, SE_GROUP_ENABLED_BY_DEFAULT.
usri3_next_index
Specifies the index of the next entry to return from the NetQueryDisplayInformation function. Pass this value as the Index parameter of NetQueryDisplayInformation to return the next logical entry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


NET_DISPLAY_MACHINE

The NET_DISPLAY_MACHINE structure contains information that an account manager can access to determine information about machine names and their attributes.

typedef struct _NET_DISPLAY_MACHINE {
    LPWSTR   usri2_name;
    LPWSTR   usri2_comment;
    DWORD    usri2_flags;
    DWORD    usri2_user_id;
    DWORD    usri2_next_index;
} NET_DISPLAY_MACHINE, *PNET_DISPLAY_MACHINE;

Members

usri2_name
A Unicode string that specifies the name of the machine to access.
usri2_comment
A Unicode string that points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_flags
Contains values that determine several features. This member can be any of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. Windows NT ignores this value.
UF_PASSWRD_NOTREQD | No password is required.
UF_PASSWRD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out (blocked). For the NetUserSetInfo function, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously locked account.
UF_DONT_EXPIRE_PASSWORD | Windows NT: Represents the password, which will never expire on the account.

The following members describe the machine type. Only one member can be set.

You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri2_user_id
Specifies the relative identifier of the machine. The relative identifier is determined by the accounts database when the machine is defined.
usri2_next_index
Specifies the index of the next entry to return from the NetQueryDisplayInformation function. Pass this value as the Index parameter of NetQueryDisplayInformation to return the next logical entry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


NET_DISPLAY_USER

The NET_DISPLAY_USER structure contains information that an account manager can access to determine information about user names, directory information for users, and user passwords.

typedef struct _NET_DISPLAY_USER {
    LPWSTR   usri1_name;
    LPWSTR   usri1_comment;
    DWORD    usri1_flags;
    LPWSTR   usri1_full_name;
    DWORD    usri1_user_id;
    DWORD    usri1_next_index;
} NET_DISPLAY_USER, *PNET_DISPLAY_USER;

Members

usri1_name
A Unicode string that specifies the name of the user account.
usri1_comment
A Unicode string that points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character (MAXCOMMENTSZ).
usri1_flags
Contains values that determine several features. This member can be any of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. Windows NT ignores this value.
UF_PASSWRD_NOTREQD | No password is required.
UF_PASSWRD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out (blocked). For the NetUserSetInfo function, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously locked account.
UF_DONT_EXPIRE_PASSWORD | Windows NT: Represents the password, which will never expire on the account.

The following members describe the account type. Only one member can be set.

usri1_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri1_user_id
Specifies the relative identifier of the user. The relative identifier is determined by the accounts database when the user is created. It uniquely defines this user account to the account manager within the domain.
usri1_next_index
Specifies the index of the next entry to return from the NetQueryDisplayInformation function. Pass this value as the Index parameter of NetQueryDisplayInformation to return the next logical entry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


PRINT_OTHER_INFO

The PRINT_OTHER_INFO structure contains information about the print job.

typedef struct _PRINT_OTHER_INFO {
    DWORD  alrtpr_jobid;
    DWORD  alrtpr_status;
    DWORD  alrtpr_submitted;
    DWORD  alrtpr_size;
}PRINT_OTHER_INFO, *PPRINT_OTHER_INFO, *LPPRINT_OTHER_INFO;

Members

alrtpr_jobid
Specifies the identification number of the print job.
alrtpr_status
Specifies the status of the print job.
alrtpr_submitted
Specifies the time at which the print job was submitted. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.
alrtpr_size
Specifies the size, in bytes, of the print job.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.

See Also

Networking (Net) Overview, Net Structures, NetAlertRaise


REPL_EDIR_INFO_0

The REPL_EDIR_INFO_0 structure selects subdirectories from the main export directory of the replicator.

typedef struct _REPL_EDIR_INFO_0 {
    LPWSTR         rped0_dirname;
} REPL_EDIR_INFO_0, *PREPL_EDIR_INFO_0, *LPREPL_EDIR_INFO_0;

Members

rped0_dirname
Specifies the name of a particular subdirectory of the main export directory.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplExportDirEnum, NetReplExportDirGetInfo


REPL_EDIR_INFO_1

The REPL_EDIR_INFO_1 structure selects subdirectories from the main export directories of replicators with the Wait Until Stabilized feature.

typedef struct _REPL_EDIR_INFO_1 {
    LPWSTR         rped1_dirname;
    DWORD          rped1_integrity;
    DWORD          rped1_extent;
} REPL_EDIR_INFO_1, *PREPL_EDIR_INFO_1, *LPREPL_EDIR_INFO_1;

Members

rped1_dirname
Specifies the name of a particular subdirectory of the main export directory.
rped1_integrity
Specifies one of the following Wait Until Stabilized options for the importer.
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the tree, it copies the entire tree to a temporary top-level directory, then renames it in the existing directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees that the entire tree matches the original tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes of the tree structure (such as date, time, name, and size), it copies the file to a temporary local file, then renames the local file in the place of the existing file. This action guarantees the integrity only of individual files, not of the entire tree.

rped1_extent
Specifies one of the following flags to select files within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated, and subdirectories or their contents will not.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplExportDirAdd, NetReplExportDirEnum, NetReplExportDirGetInfo, NetReplExportDirSetInfo


REPL_EDIR_INFO_2

The REPL_EDIR_INFO_2 structure specifies features of the export subdirectories or the entire subtree of a replicator.

typedef struct _REPL_EDIR_INFO_2 {
    LPWSTR         rped2_dirname;
    DWORD          rped2_integrity;
    DWORD          rped2_extent;
    DWORD          rped2_lockcount;
    DWORD          rped2_locktime;
} REPL_EDIR_INFO_2, *PREPL_EDIR_INFO_2, *LPREPL_EDIR_INFO_2;

Members

rped2_dirname
Specifies the name of a particular subdirectory of the main export directory.
rped2_integrity
Specifies one of the following Wait Until Stabilized options for the importer.
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the tree, it copies the entire tree to a temporary top-level directory, then renames it in the existing directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees that the entire tree matches the original tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes of the tree structure (such as date, time, name, and size), it copies the file to a temporary local file, then renames the local file in the place of the existing file. This action guarantees the integrity only of individual files, not of the entire tree.

rped2_extent
Specifies one of the following flags to select files within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated, and subdirectories or their contents will not.

rped2_lockcount
This member is the current lock count on the subdirectory; it can be modified only with the NetReplExportDirLock and NetReplExportDirUnlock functions.
rped2_locktime
This member specifies, in seconds, the time at which the directory was locked since 1970.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplExportDirLock, NetReplExportDirUnlock


REPL_EDIR_INFO_1000

The REPL_EDIR_INFO_1000 structure specifies flags that verify the integrity of the directory tree in replicators with the Wait Until Stabilized feature.

typedef struct _REPL_EDIR_INFO_1000 {
    DWORD          rped1000_integrity;
} REPL_EDIR_INFO_1000, *PREPL_EDIR_INFO_1000, *LPREPL_EDIR_INFO_1000;

Members

rped1000_integrity
Specifies one of the following Wait Until Stabilized options for the importer.
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the tree, it copies the entire tree to a temporary top-level directory, then renames it in the existing directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees that the entire tree matches the original tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes of the tree structure (such as date, time, name, and size), it copies the file to a temporary local file, then renames the local file in the place of the existing file. This action guarantees the integrity only of individual files, not of the entire tree.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplExportDirSetInfo


REPL_EDIR_INFO_1001

The REPL_EDIR_INFO_1001 structure specifies flags in the replicator to select files on the subdirectory of an exporter.

typedef struct _REPL_EDIR_INFO_1001 {
    DWORD          rped1001_extent;
} REPL_EDIR_INFO_1001, *PREPL_EDIR_INFO_1001, *LPREPL_EDIR_INFO_1001;

Members

rped1001_extent
Specifies one of the following flags to select files within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated, and subdirectories or their contents will not.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplExportDirSetInfo


REPL_IDIR_INFO_0

The REPL_IDIR_INFO_0 structure specifies subdirectories in the main import directory of the replicator.

typedef struct _REPL_IDIR_INFO_0 {
    LPWSTR         rpid0_dirname;
} REPL_IDIR_INFO_0, *PREPL_IDIR_INFO_0, *LPREPL_IDIR_INFO_0;

Members

rpid0_dirname
Specifies the name of a particular subdirectory of the main import directory.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplImportDirAdd, NetReplImportDirEnum, NetReplImportDirGetInfo


REPL_IDIR_INFO_1

The REPL_IDIR_INFO_1 structure specifies subdirectories and synchronizing states in the main import directory of the replicator.

typedef struct _REPL_IDIR_INFO_1 {
    LPWSTR         rpid1_dirname;
    DWORD          rpid1_state;
    LPWSTR         rpid1_mastername;
    DWORD          rpid1_last_update_time;
    DWORD          rpid1_lockcount;
    DWORD          rpid1_locktime;
} REPL_IDIR_INFO_1, *PREPL_IDIR_INFO_1, *LPREPL_IDIR_INFO_1;

Members

rpid1_dirname
Specifies the name of a particular subdirectory of the main import directory.
rpid1_state
Specifies the state of the named subdirectory within the main import directory. Use only one of the following values.
Value | Meaning
REPL_STATE_OK | Selects the current state of the directory.
REPL_STATE_NO_MASTER | Indicates that the selected directory is not the master directory.
REPL_STATE_NO_SYNC | Indicates that you cannot synchronize the selected directory.
REPL_STATE_NEVER_REPLICATED | Indicates that you cannot replicate the selected directory.

rpid1_mastername
Specifies the name of the exporter for the selected subdirectory.
rpid1_last_update_time
Displays the time, in seconds since 1970, at which the selected directory was last updated.
rpid1_lockcount
Indicates the current lock count on the subdirectory. You can modify this parameter only with the NetReplImportDirLock and NetReplImportDirUnlock functions.
rpid1_locktime
Indicates the time at which the directory was locked, in seconds since 1970.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplImportDirEnum, NetReplImportDirGetInfo, NetReplImportDirLock, NetReplImportDirUnlock


REPL_INFO_0

The REPL_INFO_0 structure specifies the action of the replicator, including the setting of import and export paths and parameters.

typedef struct _REPL_INFO_0 {
    DWORD          rp0_role;
    LPWSTR         rp0_exportpath;
    LPWSTR         rp0_exportlist;
    LPWSTR         rp0_importpath;
    LPWSTR         rp0_importlist;
    LPWSTR         rp0_logonusername;
    DWORD          rp0_interval;
    DWORD          rp0_pulse;
    DWORD          rp0_guardtime;
    DWORD          rp0_random;
} REPL_INFO_0, *PREPL_INFO_0, *LPREPL_INFO_0;

Members

rp0_role
Specifies either one or both of the following values.
Value | Meaning
REPL_ROLE_EXPORT | Exports directory control information.
REPL_ROLE_IMPORT | Imports directory control information on a Windows NT Workstation.

rp0_exportpath
Specifies the root directory that holds the exportpath parameter.
rp0_exportlist
Specifies the list of computers or domains to export, using semicolon delimiters. If the list is empty, the function assumes the local domain.
rp0_importpath
Specifies the root directory that holds the importpath parameter. If both the export tree and import tree are on an NTFS partition, the Windows NT Replicator service will copy the file permissions as well as the files themselves.
rp0_importlist
Specifies the list of computers or domains to import, using semicolon delimiters. If the list is empty, the function assumes the local domain.
rp0_logonusername
The account which the replication service will attempt to use if the user is not logged on.
rp0_interval
Specifies the interval in minutes (the default setting is 5), at which the exporter will contact each import server for each top-level directory. The exporter sends a sync message if it detects a change to the directory since the last message, or a pulse message if it has not.
rp0_pulse
Specifies a multiplier count (the default setting is 2) for the rp0_interval. If the exporter fails to respond to an importer after rp0_pulse times rp0_interval minutes, the importer sends a message to the exporter asking for an update. If the exporter fails again to respond after the same amount of time, the importer reports that the top level directory is not synchronized properly. If the exporter fails again to respond, the importer will no longer notify the exporter. This state is reset as soon as the importer hears from the exporter and replicates successfully.
rp0_guardtime
This setting is valid only for top-level directories when the Wait Until Stabilized feature is enabled. Before sending a synchronizing message with an updated checksum, the exporter requires that the tree not change for the time in minutes (by default). The rp0_guardtime may not be more than rp0_interval divided by 2.
rp0_random
Specifies the maximum time (default 60, maximum 120 seconds) the import servers can wait before requesting an update. An import server generates a random number of seconds (from 0 to the value of rp0_random). After receiving an update notice from the exporter, the import server waits the generated amount of seconds before requesting the replica from the export server. This prevents the export server from being overloaded by simultaneous update requests. The default value is 60. You may want to increase this value substantially if you increase rp0_interval to 60 or more minutes.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplGetInfo, NetReplSetInfo


REPL_INFO_1000

The REPL_INFO_1000 structure sets the interval that the exporter uses to access the import server for each top-level directory.

typedef struct _REPL_INFO_1000 {
    DWORD          rp1000_interval;
} REPL_INFO_1000, *PREPL_INFO_1000, *LPREPL_INFO_1000;

Members

rp1000_interval
Specifies the interval, in minutes (the default setting is 5), at which the exporter will contact each import server for each top-level directory. The exporter sends a sync message if it detects a change to the directory since the last message, or a pulse message if it has not.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplSetInfo


REPL_INFO_1001

The REPL_INFO_1001 structure specifies a count that the replicator uses to synchronize the importer to the exporter.

typedef struct _REPL_INFO_1001 {
    DWORD          rp1001_pulse;
} REPL_INFO_1001, *PREPL_INFO_1001, *LPREPL_INFO_1001;

Members

rp1001_pulse
Specifies a multiplier count (the default setting is 2) for the rp1000_interval. If the exporter fails to respond to an importer after rp1001_pulse times rp1000_interval minutes, the importer sends a message to the exporter asking for an update. If the exporter fails again to respond after the same amount of time, the importer reports that the top-level directory is not synchronized properly. If the exporter fails again to respond, the importer will no longer notify the exporter. This state is reset as soon as the importer hears from the exporter and replicates successfully.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplSetInfo


REPL_INFO_1002

The REPL_INFO_1002 structure specifies synchronizing messages for top-level directories with the Wait Until Stabilized feature.

typedef struct _REPL_INFO_1002 {
    DWORD          rp1002_guardtime;
} REPL_INFO_1002, *PREPL_INFO_1002, *LPREPL_INFO_1002;

Members

rp1002_guardtime
This setting is valid only for top-level directories when the Wait Until Stabilized feature is enabled. Before sending a synchronizing message with an updated checksum, the exporter requires that the tree not change for the time in minutes (by default). The rp1002_guardtime may not be more than rp1000_interval divided by 2.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplSetInfo


REPL_INFO_1003

The REPL_INFO_1003 structure specifies the time the import servers use to update replicating data from the export server.

typedef struct _REPL_INFO_1003 {
    DWORD          rp1003_random;
} REPL_INFO_1003, *PREPL_INFO_1003, *LPREPL_INFO_1003;

Members

rp1003_random
Specifies the maximum time the import servers can wait before requesting an update. An import server generates a random number of seconds (from 0 to the value of rp0_random). After receiving an update notice from the exporter, the import server waits the generated amount of seconds before requesting the replica from the export server. This prevents the export server from being overloaded by simultaneous update requests. The default value is 60. You may want to increase this value substantially if you increase rp1000_interval to 60 or more minutes.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmrepl.h.

See Also

Networking (Net) Overview, Net Structures, NetReplSetInfo


SERVER_INFO_100

The SERVER_INFO_100 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_100 {
    DWORD     sv100_platform_id;
    LPWSTR    sv100_name;
} SERVER_INFO_100, *PSERVER_INFO_100, *LPSERVER_INFO_100;

Members

sv100_platform_id
Indicates the information levels to use for platform-specific information.
sv100_name
A Unicode string containing the name of a server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerDiskEnum, NetServerEnum, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_101

The SERVER_INFO_101 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_101 {
    DWORD     sv101_platform_id;
    LPWSTR    sv101_name;
    DWORD     sv101_version_major;
    DWORD     sv101_version_minor;
    DWORD     sv101_type;
    LPWSTR    sv101_comment;
} SERVER_INFO_101, *PSERVER_INFO_101, *LPSERVER_INFO_101;

Members

sv101_platform_id
Indicates the information levels to use for platform-specific information.
sv101_name
A Unicode string containing the name of a server.
sv101_version_major
Specifies, in the least significant 4 bits of the byte, the major release version number of the operating system. The most significant 4 bits of the byte specifies the server type. The mask MAJOR_VERSION_MASK should be used to ensure correct results.
sv101_version_minor
Indicates the minor release version number of the operating system.
sv101_type
Describes the type of software the computer is running. This member can be one of the following values.
Symbolic constant | Value | Meaning
SV_TYPE_WORKSTATION | 0x00000001 | All LAN Manager workstations
SV_TYPE_SERVER | 0x00000002 | All LAN Manager servers
SV_TYPE_SQLSERVER | 0x00000004 | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | 0x00000008 | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | 0x00000010 | Backup domain controller
SV_TYPE_TIMESOURCE | 0x00000020 | Server running the Timesource service
SV_TYPE_AFP | 0x00000040 | Apple File Protocol servers
SV_TYPE_NOVELL | 0x00000080 | Novell servers
SV_TYPE_DOMAIN_MEMBER | 0x00000100 | LAN Manager 2.x Domain Member
SV_TYPE_LOCAL_LIST_ONLY | 0x40000000 | Servers maintained by the browser
SV_TYPE_PRINT | 0x00000200 | Server sharing print queue
SV_TYPE_DIALIN | 0x00000400 | Server running dial-in service
SV_TYPE_XENIX_SERVER | 0x00000800 | Xenix server
SV_TYPE_MFPN | 0x00004000 | Microsoft File and Print for Netware
SV_TYPE_NT | 0x00001000 | Windows NT (either Workstation or Server)
SV_TYPE_WFW | 0x00002000 | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | 0x00008000 | Windows NT non-DC server
SV_TYPE_POTENTIAL_BROWSER | 0x00010000 | Server that can run the Browser service
SV_TYPE_BACKUP_BROWSER | 0x00020000 | Server running a Browser service as backup
SV_TYPE_MASTER_BROWSER | 0x00040000 | Server running the master Browser service
SV_TYPE_DOMAIN_MASTER | 0x00080000 | Server running the domain master Browser
SV_TYPE_DOMAIN_ENUM | 0x80000000 | Primary Domain
SV_TYPE_WINDOWS | 0x00400000 | Windows 95 or later
SV_TYPE_ALL | 0xFFFFFFFF | All servers

sv101_comment
Points to a Unicode string containing a comment describing the server. The comment can be null.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerEnum, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_102

The SERVER_INFO_102 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_102 {
    DWORD     sv102_platform_id;
    LPWSTR    sv102_name;
    DWORD     sv102_version_major;
    DWORD     sv102_version_minor;
    DWORD     sv102_type;
    LPWSTR    sv102_comment;
    DWORD     sv102_users;
    LONG      sv102_disc;
    BOOL      sv102_hidden;
    DWORD     sv102_announce;
    DWORD     sv102_anndelta;
    LPWSTR    sv102_userpath;
} SERVER_INFO_102, *PSERVER_INFO_102, *LPSERVER_INFO_102;

Members

sv102_platform_id
Indicates the information levels to use for platform-specific information.
sv102_name
A Unicode string containing the name of a server.
sv102_version_major
Specifies, in the least significant 4 bits, the major release version number of the operating system. The most significant 4 bits specifies the server type. The mask MAJOR_VERSION_MASK should be used to ensure correct results.
sv102_version_minor
The minor release version number of the operating system.
sv102_type
Describes the type of software the computer is running. This member can be one of the following values:
Symbolic constant | Value | Meaning
SV_TYPE_WORKSTATION | 0x00000001 | All LAN Manager workstations
SV_TYPE_SERVER | 0x00000002 | All LAN Manager servers
SV_TYPE_SQLSERVER | 0x00000004 | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | 0x00000008 | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | 0x00000010 | Backup domain controller
SV_TYPE_TIMESOURCE | 0x00000020 | Server running the Timesource service
SV_TYPE_AFP | 0x00000040 | Apple File Protocol servers
SV_TYPE_NOVELL | 0x00000080 | Novell servers
SV_TYPE_DOMAIN_MEMBER | 0x00000100 | LAN Manager 2.x Domain Member
SV_TYPE_LOCAL_LIST_ONLY | 0x40000000 | Servers maintained by the browser
SV_TYPE_PRINT | 0x00000200 | Server sharing print queue
SV_TYPE_DIALIN | 0x00000400 | Server running dial-in service
SV_TYPE_XENIX_SERVER | 0x00000800 | Xenix server
SV_TYPE_MFPN | 0x00004000 | Microsoft File and Print for Netware
SV_TYPE_NT | 0x00001000 | Windows NT (either Workstation or Server)
SV_TYPE_WFW | 0x00002000 | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | 0x00008000 | Windows NT non-DC server
SV_TYPE_POTENTIAL_BROWSER | 0x00010000 | Server that can run the Browser service
SV_TYPE_BACKUP_BROWSER | 0x00020000 | Server running a Browser service as backup
SV_TYPE_MASTER_BROWSER | 0x00040000 | Server running the master Browser service
SV_TYPE_DOMAIN_MASTER | 0x00080000 | Server running the domain master Browser
SV_TYPE_DOMAIN_ENUM | 0x80000000 | Primary Domain
SV_TYPE_WINDOWS | 0x00400000 | Windows 95 or later
SV_TYPE_ALL | 0xFFFFFFFF | All servers

sv102_comment
Points to a Unicode string containing a comment describing the server. The comment can be null.
sv102_users
Indicates the number of users who can attempt to log on to the system server. However, it is the license server that determines how many of these users can actually log on.
sv102_disc
Indicates the auto-disconnect time, in minutes. A session is disconnected if it is idle longer than the time specified by the sv102_disc member. If the value of sv102_disc is SV_NODISC, auto-disconnect is not enabled.
sv102_hidden
Determines whether the server is visible to other computers in the same network domain. This member can be one of the following values:
Value | Meaning
SV_VISIBLE | Server is visible.
SV_HIDDEN | Server is not visible.

sv102_announce
Specifies the network announce rate, in seconds. This rate determines how often the server is announced to other computers on the network.
sv102_anndelta
Specifies the delta value or change of the announce rate, in milliseconds. This value specifies how much the announce rate can vary from the time specified in the sv102_announce member. The delta value allows randomly varied announce rates. For example, if the sv102_announce member has the value 10 and the sv102_anndelta member has the value 1, the announce rate can vary from 9.999 seconds to 10.001 seconds.
sv102_userpath
Points to a Unicode string containing the path to user directories.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_402

The SERVER_INFO_402 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_402 {
    DWORD          sv402_ulist_mtime;
    DWORD          sv402_glist_mtime;
    DWORD          sv402_alist_mtime;
    DWORD          sv402_security;
    DWORD          sv402_numadmin;
    DWORD          sv402_lanmask;
    LPWSTR         sv402_guestacct;
    DWORD          sv402_chdevs;
    DWORD          sv402_chdevq;
    DWORD          sv402_chdevjobs;
    DWORD          sv402_connections;
    DWORD          sv402_shares;
    DWORD          sv402_openfiles;
    DWORD          sv402_sessopens;
    DWORD          sv402_sessvcs;
    DWORD          sv402_sessreqs;
    DWORD          sv402_opensearch;
    DWORD          sv402_activelocks;
    DWORD          sv402_numreqbuf;
    DWORD          sv402_sizreqbuf;
    DWORD          sv402_numbigbuf;
    DWORD          sv402_numfiletasks;
    DWORD          sv402_alertsched;
    DWORD          sv402_erroralert;
    DWORD          sv402_logonalert;
    DWORD          sv402_accessalert;
    DWORD          sv402_diskalert;
    DWORD          sv402_netioalert;
    DWORD          sv402_maxauditsz;
    LPWSTR         sv402_srvheuristics;
} SERVER_INFO_402, *PSERVER_INFO_402, *LPSERVER_INFO_402;

Members

sv402_ulist_mtime
Indicates the last time (in seconds from 00:00:00, January 1,1970) the user list for servers running user-level security was modified.
sv402_glist_mtime
Indicates the last time (in seconds from 00:00:00, January 1,1970) the group list for servers running user-level security was modified.
sv402_alist_mtime
Indicates the last time (in seconds from 00:00:00, January 1,1970) the access control list for servers running user-level security was modified.
sv402_alerts
Points to a Unicode string containing the list of user names on the server. Spaces separate the names.
sv402_security
Specifies the security type of the server. This member can be one of the following:
Value | Meaning
SV_SHARESECURITY | The share level of the security type.
SV_USERSECURITY | The user level of the security type.

sv402_numadmin
Specifies how many administrators a server can accommodate at the same time.
sv402_lanmask
Determines the order in which the network device drivers are served.
sv402_guestacct
A Unicode string containing the name of a reserved guest user account for a server. The constant UNLEN specifies the maximum number of characters in the string.
sv402_chdevs
Specifies how many character-oriented devices can be shared on the server.
sv402_chdevq
Specifies how many character-oriented device queues can coexist on the server.
sv402_chdevjobs
Specifies how many character-oriented device jobs can be pending on a server.
sv402_connections
Specifies the number of connections to share names allowed on a server.
sv402_shares
Specifies the number of share names a server can accommodate.
sv402_openfiles
Specifies the number of files that can be open at once.
sv402_sessopens
Specifies the number of files that can be open in one session.
sv402_sessvcs
Specifies the maximum number of virtual circuits per client.
sv402_sessreqs
Specifies the number of simultaneous requests a client can make on any virtual circuit.
sv402_opensearch
Specifies the number of searches that can be open at once.
sv402_activelocks
Specifies the number of file locks that can be active at the same time.
sv402_numreqbuf
Specifies the number of server buffers provided.
sv402_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv402_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv402_numbigbuf
Specifies the number of 64K server buffers provided.
sv402_numfiletasks
Specifies the number of processes that can access the operating system at one time.
sv402_alertsched
Specifies the interval, in seconds, at which to notify an administrator of a network event.
sv402_erroralert
Specifies how many entries can be written to the error-log file during an interval specified in the sv402_alertsched before notifying an administrator.
sv402_logonalert
Specifies how many invalid logon attempts to allow a user before notifying an administrator.
sv402_accessalert
Specifies the number of invalid attempts to access a file to allow before notifying an administrator.
sv402_diskalertf
Specifies the number of kilobytes of free disk space remaining on the disk before the system sends a message to notify an administrator that free space for a disk is low.
sv402_netioalert
Specifies, in tenths of a percent, the network I/O error ratio allowable before notifying an administrator.
sv402_maxauditsz
Specifies, in kilobytes, the maximum size of the audit file. The audit file traces activity of the user.
sv402_srvheuristics
Points to a Unicode string of flags used to control operations on a server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_403

The SERVER_INFO_403 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_403 {
    DWORD          sv403_ulist_mtime;
    DWORD          sv403_glist_mtime;
    DWORD          sv403_alist_mtime;
    LPWSTR         sv403_alerts;
    DWORD          sv403_security;
    DWORD          sv403_numadmin;
    DWORD          sv403_lanmask;
    LPWSTR         sv403_guestacct;
    DWORD          sv403_chdevs;
    DWORD          sv403_chdevq;
    DWORD          sv403_chdevjobs;
    DWORD          sv403_connections;
    DWORD          sv403_shares;
    DWORD          sv403_openfiles;
    DWORD          sv403_sessopens;
    DWORD          sv403_sessvcs;
    DWORD          sv403_sessreqs;
    DWORD          sv403_opensearch;
    DWORD          sv403_activelocks;
    DWORD          sv403_numreqbuf;
    DWORD          sv403_sizreqbuf;
    DWORD          sv403_numbigbuf;
    DWORD          sv403_numfiletasks;
    DWORD          sv403_alertsched;
    DWORD          sv403_erroralert;
    DWORD          sv403_logonalert;
    DWORD          sv403_accessalert;
    DWORD          sv403_diskalert;
    DWORD          sv403_netioalert;
    DWORD          sv403_maxauditsz;
    LPWSTR         sv403_srvheuristics;
    DWORD          sv403_auditedevents;
     DWORD          sv403_autoprofile;
    LPWSTR         sv403_autopath;
} SERVER_INFO_403, *PSERVER_INFO_403, *LPSERVER_INFO_403;

Members

sv403_ulist_mtime
Indicates the last time (in seconds from 00:00:00, January 1,1970) that the user list for servers running user-level security was modified.
sv403_glist_mtime
Indicates the last time (in seconds from 00:00:00, January 1,1970) that the group list for servers running user-level security was modified.
sv403_alist_mtime
Indicates the last time in (seconds from 00:00:00, January 1,1970) that the access-control list for servers running user-level security was modified.
sv403_alerts
Points to a Unicode string containing the list of user names on the server. Spaces separate the names.
sv403_security
Specifies the security type of the server as follows:
Value | Meaning
SV_SHARESECURITY | Specifies the share-level security type.
SV_USERSECURITY | Specifies the user-level security type.

sv403_numadmin
Specifies the number of administrators a server can accommodate at the same time.
sv403_lanmask
Determines the order in which the network device drivers are served.
sv403_guestacct
A Unicode string containing the name of a reserved guest user account for a server. The UNLEN constant specifies the maximum number of characters in the string.
sv403_chdevs
Specifies the number of character devices that can be shared on the server.
sv403_chdevq
Specifies the number of character device queues that can coexist on the server.
sv403_chdevjobs
Specifies the number of character device jobs that can be pending on a server.
sv403_connections
Specifies the number of connections to share names allowed on a server.
sv403_shares
Specifies the number of share names a server can accommodate.
sv403_openfiles
Specifies the number of files that can be open at once.
sv403_sessopens
Specifies the number of files that can be open in one session.
sv403_sessvcs
Specifies the maximum number of virtual circuits per client.
sv403_sessreqs
Specifies the number of simultaneous requests a client can make on any virtual circuit.
sv403_opensearch
Specifies the number of searches that can be open at once.
sv403_activelocks
Specifies the number of file locks that can be active at the same time.
sv403_numreqbuf
Specifies the number of server buffers that are provided.
sv403_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv403_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv403_numbigbuf
Specifies the number of 64K server buffers provided.
sv403_numfiletasks
Specifies the number of processes that can access the operating system at the same time.
sv403_alertsched
Specifies the alert interval, in seconds, for notifying an administrator of a network event.
sv403_erroralert
Specifies how many entries can be written to the error-log file during the interval specified in the sv403_alertsched member before notifying an administrator.
sv403_logonalert
Specifies how many invalid attempts that a user tries to logon before notifying an administrator.
sv403_accessalert
Specifies how many invalid attempts to access a file to allow before notifying an administrator.
sv403_diskalertf
Specifies the number of kilobytes of free disk space remaining on the disk before sending a message to notify an administrator that free space for a disk is low.
sv403_netioalert
Specifies the network I/O error ratio, n tenths of a percent, to allow before notifying an administrator.
sv403_maxauditsz
Specifies, in kilobytes, the maximum audit file size.
sv403_srvheuristics
Points to a Unicode string of flags used to control operations on a server.
sv403_auditedevents
Specifies the audit event control mask.
sv403_autoprofile
Controls the action of the server on the profile as follows:
Value | Meaning
SW_AUTOPROF_LOAD_MASK | The server loads the profile.
SW_AUTOPROF_SAVE_MASK | The server saves the profile.

sv403_autopath
Points to the path for the profile.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_502

The SERVER_INFO_502 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_502 {
    DWORD    sv502_sessopens;
    DWORD    sv502_sessvcs;
    DWORD    sv502_opensearch;
    DWORD    sv502_sizreqbuf;
    DWORD    sv502_initworkitems;
    DWORD    sv502_maxworkitems;
    DWORD    sv502_rawworkitems;
    DWORD    sv502_irpstacksize;
    DWORD    sv502_maxrawbuflen;
    DWORD    sv502_sessusers;
    DWORD    sv502_sessconns;
    DWORD    sv502_maxpagedmemoryusage;
    DWORD    sv502_maxnonpagedmemoryusage;
    BOOL     sv502_enableforcedlogoff;
    BOOL     sv502_timesource;
    BOOL     sv502_acceptdownlevelapis;
    BOOL     sv502_lmannounce;
} SERVER_INFO_502, *PSERVER_INFO_502, *LPSERVER_INFO_502;

Members

sv502_sessopens
Specifies the number of files that can be open in one session.
sv502_sessvcs
Specifies the maximum number of virtual circuits per client.
sv502_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv502_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv502_initworkitems
Specifies the initial number of receive buffers, or work items, used by the server. Allocating work items costs a certain amount of memory initially, but not as much as having to allocate additional buffers later.
sv502_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport must initiate flow control at a significant performance cost.
sv502_rawworkitems
Specifies the number of special work items for raw I/O that the server uses. A larger value for this member can increase performance but costs more memory.
sv502_irpstacksize
Specifies the number of stack locations in IRPs allocated by the server.
sv502_maxrawbuflen
Specifies the maximum raw mode buffer size.
sv502_sessusers
Specifies the maximum number of users that can be logged on to a server using a single virtual circuit.
sv502_sessconns
Specifies the maximum number of tree connections that can be made on the server using a single virtual circuit.
sv502_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
sv502_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
sv502_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
sv502_timesource
Specifies whether the server is a reliable time source.
sv502_acceptdownlevelapis
Specifies whether the server will accept function calls from previous generation LAN Manager clients.
sv502_lmannounce
Specifies the LAN Manager server announcement interval.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_503

The SERVER_INFO_503 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_503 {
    DWORD     sv503_sessopens;
    DWORD     sv503_sessvcs;
    DWORD     sv503_opensearch;
    DWORD     sv503_sizreqbuf;
    DWORD     sv503_initworkitems;
    DWORD     sv503_maxworkitems;
    DWORD     sv503_rawworkitems;
    DWORD     sv503_irpstacksize;
    DWORD     sv503_maxrawbuflen;
    DWORD     sv503_sessusers;
    DWORD     sv503_sessconns;
    DWORD     sv503_maxpagedmemoryusage;
    DWORD     sv503_maxnonpagedmemoryusage;
    BOOL      sv503_enableforcedlogoff;
    BOOL      sv503_timesource;
    BOOL      sv503_acceptdownlevelapis;
    BOOL      sv503_lmannounce;
    LPWSTR    sv503_domain;
    DWORD     sv503_maxkeepsearch;
    DWORD     sv503_scavtimeout;
    DWORD     sv503_minrcvqueue;
    DWORD     sv503_minfreeworkitems;
    DWORD     sv503_xactmemsize;
    DWORD     sv503_threadpriority;
    DWORD     sv503_maxmpxct;
    DWORD     sv503_oplockbreakwait;
    DWORD     sv503_oplockbreakresponsewait;
    BOOL      sv503_enableoplocks;
    BOOL      sv503_enablefcbopens;
    BOOL      sv503_enableraw;
    BOOL      sv503_enablesharednetdrives;
    DWORD     sv503_minfreeconnections;
    DWORD     sv503_maxfreeconnections;
} SERVER_INFO_503, *PSERVER_INFO_503, *LPSERVER_INFO_503;

Members

sv503_sessopens
Specifies the number of files that can be open in one session.
sv503_sessvcs
Specifies the maximum number of virtual circuits per client.
sv503_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv503_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv503_initworkitems
Specifies the initial number of receive buffers, or work items, used by the server. Allocating work items costs a certain amount of memory initially, but not as much as having to allocate additional buffers later.
sv503_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport must initiate flow control at a significant performance cost.
sv503_rawworkitems
Specifies the number of special work items for raw I/O that the server uses. A larger value for this member can increase performance but costs more memory.
sv503_irpstacksize
Specifies the number of stack locations in IRPs allocated by the server.
sv503_maxrawbuflen
Specifies the maximum raw mode buffer size.
sv503_sessusers
Specifies the maximum number of users that can be logged on to a server using a single virtual circuit.
sv503_sessconns
Specifies the maximum number of tree connections that can be made on the server using a single virtual circuit.
sv503_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
sv503_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
sv503_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
sv503_timesource
Specifies whether the server is a reliable time source.
sv503_acceptdownlevelapis
Specifies whether the server will accept function calls from previous generation LAN Manager clients.
sv503_lmannounce
Specifies the operating system server announcement interval.
sv503_domain
Specifies the name of the server's domain.
sv503_maxkeepsearch
Specifies the length of time the server will retain information about directory searches that have not ended.
sv503_scavtimeout
Specifies the time that the scavenger remains idle before waking up to service requests. A smaller value for this member improves the response of the server to various events but costs CPU cycles.
sv503_minrcvqueue
Specifies the minimum number of free receive work items needed by the server before it begins allocating more. A larger value for this member helps ensure that there will always be work items available, but a value that is too large is simply inefficient.
sv503_minfreeworkitems
Specifies the minimum number of available receive work items that are needed for the server to begin processing a server message block. A larger value for this member ensures that work items are available more frequently for nonblocking requests, but it also increases the likelihood that blocking requests will be rejected.
sv503_xactmemsize
Specifies the size of the shared memory region used to process server functions.
sv503_threadpriority
Specifies the priority of all server threads in relation to the base priority of the process. Higher priority can give better server performance at the cost of local responsiveness. Lower priority balances server needs with the needs of other processes on the system.
sv503_maxmpxct
Specifies the maximum number of simultaneous requests any one client can send to the server. For example, 10 means you can have 10 unanswered requests at the server. When any single client has 10 requests queued within the server, the client must wait for a server response before sending another request.
sv503_oplockbreakwait
Specifies the time to wait before timing out an opportunistic lock break request.
sv503_oplockbreakresponsewait
Specifies the time to wait before timing out an opportunistic lock break request.
sv503_enableoplocks
Specifies whether the server allows clients to use opportunistic locks on files. Opportunistic locks are a significant performance enhancement, but have the potential to cause lost cached data on some networks, particularly wide-area networks.
sv503_enablefcbopens
Specifies whether several MS-DOS File Control Blocks (FCBs) are placed in a single location accessible by the server. This saves resources on the server.
sv503_enableraw
Specifies whether the server processes raw Server Message Blocks (SMBs). If enabled, this allows more data to transfer per transaction and also improves performance. However, it is possible that processing raw SMBs can impede performance on certain networks. The server maintains the value of this member.
sv503_enablesharednetdrives
Specifies whether the server allows redirected server drives to be shared.
sv503_minfreeconnections
Specifies the minimum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.
sv503_maxfreeconnections
Specifies the maximum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1005

The SERVER_INFO_1005 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1005 {
    LPWSTR    sv1005_comment;
} SERVER_INFO_1005, *PSERVER_INFO_1005, *LPSERVER_INFO_1005;

Members

sv1005_comment
Points to a Unicode string that contains a comment describing the server. The comment can be null.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1107

The SERVER_INFO_1107 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1107 {
   DWORD    sv1107_users;
} SERVER_INFO_1107, *PSERVER_INFO_1107, *LPSERVER_INFO_1107;

Members

sv1107_users
Indicates the number of users allowed on the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1010

The SERVER_INFO_1010 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1010 {
    LONG    sv1010_disc;
} SERVER_INFO_1010, *PSERVER_INFO_1010, *LPSERVER_INFO_1010;

Members

sv1010_disc
Indicates the auto-disconnect time, in minutes. A session is disconnected if it is idle longer than the time specified by this member. If the value of sv1010_disc is SV_NODISC, auto-disconnect is not enabled.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1016

The SERVER_INFO_1016 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1016 {
    BOOL    sv1016_hidden;
} SERVER_INFO_1016, *PSERVER_INFO_1016, *LPSERVER_INFO_1016;

Members

sv1016_hidden
Determines whether the server is visible to other computers in the same network domain. This member can be one of the following values:
Value | Meaning
SV_VISIBLE | The server is visible.
SV_HIDDEN | The server is not visible.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1017

The SERVER_INFO_1017 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1017 {
    DWORD    sv1017_announce;
} SERVER_INFO_1017, *PSERVER_INFO_1017, *LPSERVER_INFO_1017;

Members

sv1017_announce
Specifies the network announce rate, in seconds. This rate determines how often the server is announced to other computers on the network.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1018

The SERVER_INFO_1018 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1018 {
    DWORD    sv1018_anndelta;
} SERVER_INFO_1018, *PSERVER_INFO_1018, *LPSERVER_INFO_1018;

Members

sv1018_anndelta
Specifies the delta or change of the announce rate,in milliseconds. This value specifies how much the announce rate can vary from the time specified in the sv2_announce member or sv1017_announce. The delta value allows randomly varied announce rates. For example, if sv2_announce has the value 10 and sv1018_anndelta has the value 1, the announce rate can vary from 9.999 seconds to 10.001 seconds.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1501

The SERVER_INFO_1501 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1501 {
    DWORD    sv1501_sessopens;
} SERVER_INFO_1501, *PSERVER_INFO_1501, *LPSERVER_INFO_1501;

Members

sv1501_sessopens
Specifies the number of files that can be open in one session.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1502

The SERVER_INFO_1502 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1502 {
    DWORD    sv1502_sessvcs;
} SERVER_INFO_1502, *PSERVER_INFO_1502, *LPSERVER_INFO_1502;

Members

sv1502_sessvcs
Specifies the maximum number of virtual circuits per client.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1503

The SERVER_INFO_1503 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1503 {
    DWORD    sv1503_opensearch;
} SERVER_INFO_1503, *PSERVER_INFO_1503, *LPSERVER_INFO_1503;

Members

sv1503_opensearch
Specifies the number of search operations that can be carried out simultaneously.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1506

The SERVER_INFO_1506 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1506 {
    DWORD    sv1506_maxworkitems;
} SERVER_INFO_1506, *PSERVER_INFO_1506, *LPSERVER_INFO_1506;

Members

sv1506_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport protocol must initiate flow control at a significant cost to performance.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1509

The SERVER_INFO_1509 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1509 {
    DWORD    sv1509_maxrawbuflen;
} SERVER_INFO_1509, *PSERVER_INFO_1509, *LPSERVER_INFO_1509;

Members

sv1509_maxrawbuflen
Specifies the maximum raw mode buffer size.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1510

The SERVER_INFO_1510 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1510 {
    DWORD    sv1510_sessusers;
} SERVER_INFO_1510, *PSERVER_INFO_1510, *LPSERVER_INFO_1510;

Members

sv1510_sessusers
Specifies the maximum number of users that can be logged on to a server using a single virtual circuit.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1511

The SERVER_INFO_1511 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1511 {
    DWORD    sv1511_sessconns;
} SERVER_INFO_1511, *PSERVER_INFO_1511, *LPSERVER_INFO_1511;

Members

sv1511_sessconns
Specifies the maximum number of tree connections that users can make with a single virtual circuit.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1512

The SERVER_INFO_1512 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1512 {
    DWORD    sv1512_maxnonpagedmemoryusage;
} SERVER_INFO_1512, *PSERVER_INFO_1512, *LPSERVER_INFO_1512;

Members

sv1512_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can have allocated at any time. Adjust this member if you want to administer memory quota control.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1513

The SERVER_INFO_1513 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1513 {
    DWORD    sv1513_maxpagedmemoryusage;
} SERVER_INFO_1513, *PSERVER_INFO_1513, *LPSERVER_INFO_1513;

Members

sv1513_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server allocates at any particular time. Adjust this member if you want to administer memory quota control.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1515

The SERVER_INFO_1515 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1515 {
    BOOL    sv1515_enableforcedlogoff;
} SERVER_INFO_1515, *PSERVER_INFO_1515, *LPSERVER_INFO_1515;

Members

sv1515_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1516

The SERVER_INFO_1516 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1516 {
    BOOL    sv1516_timesource;
} SERVER_INFO_1516, *PSERVER_INFO_1516, *LPSERVER_INFO_1516;

Members

sv1516_timesource
Specifies whether the server is a reliable time source.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1518

The SERVER_INFO_1518 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1518 {
    BOOL    sv1518_lmannounce;
} SERVER_INFO_1518, *PSERVER_INFO_1518, *LPSERVER_INFO_1518;

Members

sv1518_lmannounce
Specifies the interval of operating system server announcements, in seconds.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1523

The SERVER_INFO_1523 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1523 {
    DWORD    sv1523_maxkeepsearch;
} SERVER_INFO_1523, *PSERVER_INFO_1523, *LPSERVER_INFO_1523;

Members

sv1523_maxkeepsearch
Specifies the length of time the server will retain information about directory search operations that have not ended.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1528

The SERVER_INFO_1528 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1528 {
    DWORD    sv1528_scavtimeout;
} SERVER_INFO_1528, *PSERVER_INFO_1528, *LPSERVER_INFO_1528;

Members

sv1528_scavtimeout
Specifies the time that the scavenger remains idle before waking up to service requests. A smaller value for this member improves the response of the server to various events but costs CPU cycles.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1529

The SERVER_INFO_1529 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1529 {
    DWORD    sv1529_minrcvqueue;
} SERVER_INFO_1529, *PSERVER_INFO_1529, *LPSERVER_INFO_1529;

Members

sv1529_minrcvqueue
Specifies the minimum number of free receive work items needed by the server before it begins allocating more. A larger value for this member helps ensure that there will always be work items available, but a value that is too large is simply inefficient.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1530

The SERVER_INFO_1530 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1530 {
    DWORD    sv1530_minfreeworkitems;
} SERVER_INFO_1530, *PSERVER_INFO_1530, *LPSERVER_INFO_1530;

Members

sv1530_minfreeworkitems
Specifies the minimum number of available receive work items that are needed for the server to begin processing a server message block. A larger value for this member ensures that work items are available more frequently for nonblocking requests, but it also increases the likelihood that blocking requests will be rejected.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1533

The SERVER_INFO_1533 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1533 {
    DWORD    sv1533_maxmpxct;
} SERVER_INFO_1533, *PSERVER_INFO_1533, *LPSERVER_INFO_1533;

Members

sv1533_maxmpxct
Specifies the maximum number of simultaneous requests any one client can send to the server. For example, 10 means you can have 10 unanswered requests at the server. When any single client has 10 requests queued within the server, the client must wait for a server response before sending another request.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1534

The SERVER_INFO_1534 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1534 {
    DWORD    sv1534_oplockbreakwait;
} SERVER_INFO_1534, *PSERVER_INFO_1534, *LPSERVER_INFO_1534;

Members

sv1534_oplockbreakwait
Specifies the time to wait before timing out a request for an opportunistic lock.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1535

The SERVER_INFO_1535 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1535 {
    DWORD    sv1535_oplockbreakresponsewait;
} SERVER_INFO_1535, *PSERVER_INFO_1535, *LPSERVER_INFO_1535;

Members

sv1535_oplockbreakresponsewait
Specifies the time to wait before timing out a request for an opportunistic lock.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1536

The SERVER_INFO_1536 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1536 {
    BOOL    sv1536_enableoplocks;
} SERVER_INFO_1536, *PSERVER_INFO_1536, *LPSERVER_INFO_1536;

Members

sv1536_enableoplocks
Specifies whether the server allows clients to use oplocks on files. Opportunistic locks are a significant performance enhancement, but have the potential to cause lost cached data on some networks, particularly wide-area networks.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1538

The SERVER_INFO_1538 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1538 {
    BOOL    sv1538_enablefcbopens;
} SERVER_INFO_1538, *PSERVER_INFO_1538, *LPSERVER_INFO_1538;

Members

sv1538_enablefcbopens
Specifies whether several MS-DOS File Control Blocks (FCBs) are placed in a single location accessible by the server. This saves resources on the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1539

The SERVER_INFO_1539 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1539 {
    BOOL    sv1539_enableraw;
} SERVER_INFO_1539, *PSERVER_INFO_1539, *LPSERVER_INFO_1539;

Members

sv1539_enableraw
Specifies whether the server processes raw Server Message Blocks (SMBs). If enabled, this member allows more data to be transferred per transaction and improves performance. However, it is possible that processing raw SMBs can impede performance on certain networks. The server maintains the value of this member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1540

The SERVER_INFO_1540 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1540 {
    BOOL    sv1540_enablesharednetdrives;
} SERVER_INFO_1540, *PSERVER_INFO_1540, *LPSERVER_INFO_1540;

Members

sv1540_enablesharednetdrives
Specifies whether the server allows redirected server drives to be shared.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1541

The SERVER_INFO_1541 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1541 {
    BOOL    sv1541_minfreeconnections;
} SERVER_INFO_1541, *PSERVER_INFO_1541, *LPSERVER_INFO_1541;

Members

sv1541_minfreeconnections
Specifies the minimum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1542

The SERVER_INFO_1542 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1542 {
    BOOL    sv1542_maxfreeconnections;
} SERVER_INFO_1542, *PSERVER_INFO_1542, *LPSERVER_INFO_1542;

Members

sv1542_maxfreeconnections
Specifies the maximum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1544

The SERVER_INFO_1544 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1544 {
    DWORD    sv1544_initconntable;
} SERVER_INFO_1544, *PSERVER_INFO_1544, *LPSERVER_INFO_1544;

Members

sv1544_initconntable
Specifies the initial number of tree connections to be allocated in the connection table. The server automatically increases the table as necessary, so setting the member to a higher value is an optimization.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1550

The SERVER_INFO_1550 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1550 {
    DWORD    sv1550_diskspacethreshold;
} SERVER_INFO_1550, *PSERVER_INFO_1550, *LPSERVER_INFO_1550;

Members

sv1550_diskspacethreshold
Specifies the percentage of free disk space remaining before an alert message is sent.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_INFO_1552

The SERVER_INFO_1552 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_1552 {
    DWORD    sv1552_maxlinkdelay;
} SERVER_INFO_1552, *PSERVER_INFO_1552, *LPSERVER_INFO_1552;

Members

sv1552_maxlinkdelay
Specifies the maximum time allowed for a link delay, in seconds. If delays exceed this number, the server disables raw I/O for this connection.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerGetInfo


SERVER_TRANSPORT_INFO_0

The SERVER_TRANSPORT_INFO_0 structure contains information about the specified transporter, including name, address, and location on the network.

typedef struct _SERVER_TRANSPORT_INFO_0 {
    DWORD     svti0_numberofvcs;
    LPWSTR    svti0_transportname;
    [size_is(svti0_transportaddresslength)]    LPBYTE svti0_transportaddress;
    DWORD     svti0_transportaddresslength;
    LPWSTR    svti0_networkaddress;
} SERVER_TRANSPORT_INFO_0, *PSERVER_TRANSPORT_INFO_0, *LPSERVER_TRANSPORT_INFO_0;

#else

typedef struct _SERVER_TRANSPORT_INFO_0 {
    DWORD     svti0_numberofvcs;
    LPWSTR    svti0_transportname;
    LPBYTE    svti0_transportaddress;
    DWORD     svti0_transportaddresslength;
    LPWSTR    svti0_networkaddress;
} SERVER_TRANSPORT_INFO_0, *PSERVER_TRANSPORT_INFO_0, *LPSERVER_TRANSPORT_INFO_0;

#endif

Members

svti0_numberofvcs
Specifies the number of clients communicating with the server using this transport.
svti0_transportname
Specifies the device name of the transport.
svti0_transportaddress
Specifies the address of the server on this transport.
svti0_transportaddresslength
Specifies the length, in bytes, of the svti0_transportaddress member.
svti0_networkaddress
A null-terminated string representing the network address.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmserver.h.

See Also

Networking (Net) Overview, Net Structures, NetServerTransportAdd


SERVICE_INFO_0

The SERVICE_INFO_0 structure contains the name of a network service.

typedef struct _SERVICE_INFO_0 {
    LPWSTR  svci0_name;
} SERVICE_INFO_0, *PSERVICE_INFO_0, * LPSERVICE_INFO_0;

Members

svci0_name
A Unicode string containing the name of the network service to monitor.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.

See Also

Networking (Net) Overview, Net Structures, NetServiceEnum, NetServiceGetInfo


SERVICE_INFO_1

The SERVICE_INFO_1 structure contains name, status, service code, and identifcation number of a network service.

typedef struct _SERVICE_INFO_1 {
    LPWSTR  svci1_name;
    DWORD   svci1_status;
    DWORD   svci1_code;
    DWORD   svci1_pid;
} SERVICE_INFO_1, *PSERVICE_INFO_1, * LPSERVICE_INFO_1;

Members

svci1_name
A Unicode string containing the name of the network service to monitor.
svci1_status
Specifies the status of the connection.
svci1_code
The return code returned if the designated service fails to install properly.
svci1_pid
Specifies the service process identification.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.

See Also

Networking (Net) Overview, Net Structures, NetServiceEnum, NetServiceGetInfo


SERVICE_INFO_2

The SERVICE_INFO_2 structure describes attributes of the network service.

typedef struct _SERVICE_INFO_2 {
    LPWSTR  svci2_name;
    DWORD   svci2_status;
    DWORD   svci2_code;
    DWORD   svci2_pid;
    LPWSTR  svci2_text;
    DWORD   svci2_specific_error;
    LPWSTR  svci2_display_name;
} SERVICE_INFO_2, *PSERVICE_INFO_2, * LPSERVICE_INFO_2;

Members

svci2_name
A Unicode string containing the name of the network service to monitor.
svci2_status
Specifies the status of the connection.
svci2_code
The return code returned if the designated service fails to install properly.
svci2_pid
Specifies the service process identification.
svci2_text
Specifies text describing the service.
svci2_specific_error
Specifies the error returned if the designated service fails to install properly or if an error occurs during service.
svci2_display_name
Specifies the name of the display type for the net service.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmsvc.h.

See Also

Networking (Net) Overview, Net Structures, NetServiceEnum, NetServiceGetInfo, NetServiceInstall


SESSION_INFO_0

The SESSION_INFO_0 structure contains information about the session, including name of the computer; name of the user; and files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_0 {
    LPWSTR    sesi0_cname;  // client name (no backslashes)
} SESSION_INFO_0, *PSESSION_INFO_0, *LPSESSION_INFO_0;

Members

sesi0_cname
Points to a Unicode string that contains the name of the computer that established the session.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetSessionEnum, NetSessionGetInfo


SESSION_INFO_1

The SESSION_INFO_1 structure contains information about the session, including name of the computer; name of the user; and files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_1 {
    LPWSTR    sesi1_cname;  // client name (no backslashes)
    LPWSTR    sesi1_username;
    DWORD     sesi1_time;
    DWORD     sesi1_idle_time;
    DWORD     sesi1_user_flags;
} SESSION_INFO_1, *PSESSION_INFO_1, *LPSESSION_INFO_1;

Members

sesi1_cname
Points to a Unicode string containing the name of the computer that established the session.
sesi1_username
Points to a Unicode string containing the name of the user who established the session.
sesi1_num_opens
Displays the number of files, devices, and pipes opened during the session.
sesi1_time
Specifies the number of seconds a session has been active.
sesi1_idle_time
Specifies the number of seconds a session has been idle.
sesi1_user_flags
Describes how the user established the session. This member can be one of the following values:
Value | Meaning
SESS_GUEST | The sesi1_username member established the session using a guest account.
SESS_NOENCRYPTION | The sesi1_username member established the session without using password encryption.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetSessionEnum, NetSessionGetInfo


SESSION_INFO_2

The SESSION_INFO_2 structure contains information about the session, including name of the computer; name of the user; and files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_2{
    LPWSTR    sesi2_cname;  // client name (no backslashes)
    LPWSTR    sesi2_username;
    DWORD     sesi2_num_opens;
    DWORD     sesi2_time;
    DWORD     sesi2_idle_time;
    DWORD     sesi2_user_flags;
    LPWSTR    sesi2_cltype_name;
} SESSION_INFO_2, *PSESSION_INFO_2, *LPSESSION_INFO_2;

Members

sesi2_cname
Points to a Unicode string containing the name of the computer that established the session.
sesi2_username
Points to a Unicode string containing the name of the user who established the session.
sesi2_num_opens
Displays the number of files, devices, and pipes opened during the session.
sesi2_time
Specifies the number of seconds a session has been active.
sesi2_idle_time
Specifies the number of seconds a session has been idle.
sesi2_user_flags
Describes how the user established the session. This member can be one of the following values:
Value | Meaning
SESS_GUEST | The sesi2_username member established the session using a guest account.
SESS_NOENCRYPTION | The sesi2_username member established the session without using password encryption.

sesi2_cltype_name
Points to a Unicode string that specifies the type of client that established the session. Following are the defined types for LAN Manager servers:
Value | Meaning
DOS LM 1.0 | LAN Manager for MS-DOS 1.0 clients.
DOS LM 2.0 | LAN Manager for MS-DOS 2.0 clients.
OS/2 LM 1.0 | LAN Manager for MS-OS/2 1.0 clients.
OS/2 LM 2.0 | LAN Manager for MS-OS/2 2.0 clients.

Sessions from LAN Manager servers running UNIX also will appear as LAN Manager 2.0.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetSessionEnum, NetSessionGetInfo


SESSION_INFO_10

The SESSION_INFO_10 structure contains information about the session, including name of the computer; name of the user; and files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_10 {
    LPWSTR    sesi10_cname; // client name (no backslashes)
    LPWSTR    sesi10_username;
    DWORD     sesi10_time;
    DWORD     sesi10_idle_time;
} SESSION_INFO_10, *PSESSION_INFO_10, *LPSESSION_INFO_10;

Members

sesi10_cname
Points to a Unicode string containing the name of the computer that established the session.
sesi10_username
Points to a Unicode string containing the name of the user who established the session.
sesi10_time
Specifies the number of seconds a session has been active.
sesi10_idle_time
Specifies the number of seconds a session has been idle.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetSessionEnum, NetSessionGetInfo


SESSION_INFO_502

The SESSION_INFO_502 structure contains information about the session, including name of the computer; name of the user; and files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_502 {
    LPWSTR    sesi502_cname; // client name (no backslashes)
    LPWSTR    sesi502_username;
    DWORD     sesi502_num_opens;
    DWORD     sesi502_time;
    DWORD     sesi502_idle_time;
    DWORD     sesi502_user_flags;
    LPWSTR    sesi502_cltype_name;
    LPWSTR    sesi502_transport;
} SESSION_INFO_502, *PSESSION_INFO_502, *LPSESSION_INFO_502;

Members

sesi502_cname
Points to a Unicode string containing the name of the computer that established the session.
sesi502_username
Points to a Unicode string containing the name of the user who established the session.
sesi502_num_opens
Displays the number of files, devices, and pipes opened during the session.
sesi502_time
Specifies the number of seconds a session has been active.
sesi502_idle_time
Specifies the number of seconds a session has been idle.
sesi502_user_flags
Describes how the user established the session. This member can be one of the following values:
Value | Meaning
SESS_GUEST | The sesi502_username member established the session using a guest account.
SESS_NOENCRYPTION | The sesi502_username member established the session without using password encryption.

sesi502_cltype_name
Points to a Unicode string that specifies the type of client that established the session. Following are the defined types for LAN Manager servers:
Value | Meaning
DOS LM 1.0 | LAN Manager for MS-DOS 1.0 clients.
DOS LM 2.0 | LAN Manager for MS-DOS 2.0 clients.
OS/2 LM 1.0 | LAN Manager for MS-OS/2 1.0 clients.
OS/2 LM 2.0 | LAN Manager for MS-OS/2 2.0 clients.

Sessions from LAN Manager servers running UNIX also will appear as LAN Manager 2.0.

sesi502_transport
Specifies the name of the transport that the client is using to communicate with the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetSessionEnum


SHARE_INFO_0

The SHARE_INFO_0 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_0 {
    LPWSTR    shi0_netname;
} SHARE_INFO_0, *PSHARE_INFO_0, *LPSHARE_INFO_0;

Members

shi0_netname
A Unicode string containing the sharename of a resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareEnum, NetShareGetInfo


SHARE_INFO_1

The SHARE_INFO_1 structure contains information about the shared resource, including name of the resource, type and permissions, and the number of connections.

typedef struct _SHARE_INFO_1 {
    LPWSTR    shi1_netname;
    DWORD     shi1_type;
    LPWSTR    shi1_remark;
} SHARE_INFO_1, *PSHARE_INFO_1, *LPSHARE_INFO_1;

Members

shi1_netname
A Unicode string containing the sharename of a resource.
shi1_type
This member can be one of following types.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess Communication (IPC)

shi1_remark
Points to a Unicode string containing an optional comment about the shared resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareEnum, NetShareGetInfo, NetShareSetInfo


SHARE_INFO_2

The SHARE_INFO_2 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_2 {
    LPWSTR    shi2_netname;
    DWORD     shi2_type;
    LPWSTR    shi2_remark;
    DWORD     shi2_permissions;
    DWORD     shi2_max_uses;
    DWORD     shi2_current_uses;
    LPWSTR    shi2_path;
    LPWSTR    shi2_passwd;
} SHARE_INFO_2, *PSHARE_INFO_2, *LPSHARE_INFO_2;

Members

shi2_netname
A Unicode string containing the sharename of a resource.
shi2_type
This member can be one of the following types:
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess Communication (IPC)

shi2_remark
Points to a Unicode string that contains an optional comment about the shared resource.
shi2_permissions
Specifies the shared resource's permissions for servers running with share-level security. A server running user-level security ignores this member.This member can be one or more of the following values.
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource as the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.

shi2_max_uses
Indicates the maximum number of concurrent connections that the shared resource can accommodate (unlimited if the value specified in shi2_max_uses is -1).
shi2_current_uses
Specifies the number of current connections to the resource.
shi2_path
Points to a Unicode string containing the local path for the shared resource. For disks, shi2_path is the path being shared. For print queues, shi2_path is the name of the print queue being shared.
shi2_passwd
Specifies the share's password (when the server is running with share-level security). If the server is running with user-level security, shi2_passwd is ignored. The shi2_passwd member can be no longer than SHPWLEN+1 bytes (including a terminating null character).

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo


SHARE_INFO_501

The SHARE_INFO_501 structure contains information about the shared resource, including name of the resource, type and permissions, and the number of connections.

typedef struct _SHARE_INFO_501 {
    LPWSTR    shi501_netname;
    DWORD     shi501_type;
    LPWSTR    shi501_remark;
    DWORD     shi501_flag;
} SHARE_INFO_501, *PSHARE_INFO_501, *LPSHARE_INFO_501;

Members

shi501_netname
A Unicode string containing the sharename of a resource.
Shi501_type
One of the following four values specifying the type of share:
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess Communication (IPC)

shi501_remark
Points to a Unicode string containing an optional comment about the shared resource.
shi501_flag
Sets the following flag value:
Value | Meaning
CSC_CACHEABLE | This flag is an advisory to clients stating that, if they wish and are able, they can legitimately and automatically cache files on this share for access when the client is disconnected from the network.

See Also

Networking (Net) Overview, Net Structures


SHARE_INFO_502

The SHARE_INFO_502 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_502 {
    LPWSTR    shi502_netname;
    DWORD     shi502_type;
    LPWSTR    shi502_remark;
    DWORD     shi502_permissions;
    DWORD     shi502_max_uses;
    DWORD     shi502_current_uses;
    LPWSTR    shi502_path;
    LPWSTR    shi502_passwd;
    DWORD     shi502_reserved;
    PSECURITY_DESCRIPTOR  shi502_security_descriptor;
} SHARE_INFO_502, *PSHARE_INFO_502, *LPSHARE_INFO_502;

Members

shi502_netname
A Unicode string containing the sharename of a resource.
shi502_type
One of the following four values specifying the type of share:
Value | Meaning
STYPE_DISKTREE | Disk Drive
STYPE_PRINTQ | Print Queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess Communication (IPC)

shi502_remark
Points to a Unicode string containing an optional comment about the shared resource.
shi502_permissions
Specifies the shared resource's permissions for servers running with share-level security.This member is ignored on a server running user-level security. This member can be any of the following values:
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource as the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.

shi502_max_uses
Indicates the maximum number of concurrent connections that the shared resource can accommodate (unlimited if the value specified in shi502_max_uses is -1).
shi502_current_uses
Specifies the number of current connections to the resource.
shi502_path
Points to a Unicode string that contains the local path for the shared resource. For disks, shi502_path is the path being shared. For print queues, shi502_path is the name of the print queue being shared.
shi502_passwd
Specifies the share's password (when the server is running with share-level security). If the server is running with user-level security, shi502_passwd is ignored. The shi502_passwd member can be no longer than SHPWLEN+1 bytes (including a terminating null character).
shi502_reserved
Must be zero.
shi502_security_descriptor
Specifies the security descriptor associated with this share.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo


SHARE_INFO_1004

The SHARE_INFO_1004 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_1004 {
    LPWSTR    shi1004_remark;
} SHARE_INFO_1004, *PSHARE_INFO_1004, *LPSHARE_INFO_1004;

Members

shi1004_remark
Points to a Unicode string that contains an optional comment about the shared resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareSetInfo


SHARE_INFO_1006

The SHARE_INFO_1006 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_1006 {
    DWORD    shi1006_max_uses;
} SHARE_INFO_1006, *PSHARE_INFO_1006, *LPSHARE_INFO_1006;

Members

shi1006_max_uses
Indicates the maximum number of concurrent connections that the shared resource can accommodate (unlimited if the value specified in shi1006_max_uses is -1).

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareSetInfo


SHARE_INFO_1501

The SHARE_INFO_1501 structure contains information about the shared resource, including name of the resource, type and permissions, and number of connections.

typedef struct _SHARE_INFO_1501 {
    DWORD    shi1501_reserved;
    PSECURITY_DESCRIPTOR    shi1501_security_descriptor;
} SHARE_INFO_1501, *PSHARE_INFO_1501, *LPSHARE_INFO_1501;

Members

shi1501_reserved
Must be zero.
shi1501_security_descriptor
Specifies the security descriptor associated with this share.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lmshare.h.

See Also

Networking (Net) Overview, Net Structures, NetShareSetInfo


STAT_SERVER_0

The STAT_SERVER_0 structure contains statistical information about the server.

typedef struct _STAT_SERVER_0 {
    DWORD          sts0_start;
    DWORD          sts0_fopens;
    DWORD          sts0_devopens;
    DWORD          sts0_jobsqueued;
    DWORD          sts0_sopens;
    DWORD          sts0_stimedout;
    DWORD          sts0_serrorout;
    DWORD          sts0_pwerrors;
    DWORD          sts0_permerrors;
    DWORD          sts0_syserrors;
    DWORD          sts0_bytessent_low;
    DWORD          sts0_bytessent_high;
    DWORD          sts0_bytesrcvd_low;
    DWORD          sts0_bytesrcvd_high;
    DWORD          sts0_avresponse;
    DWORD          sts0_reqbufneed;
    DWORD          sts0_bigbufneed;
} STAT_SERVER_0, *PSTAT_SERVER_0, *LPSTAT_SERVER_0;

Members

sts0_start
Specifies the time statistics collection started. This element also indicates when the statistics were last cleared. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. To calculate the length of time that statistics have been collected, subtract this value from the present time.
sts0_fopens
Specifies the number of times a file is opened on a server. This includes the number of times named pipes are opened.
sts0_devopens
Specifies the number of times a server device is opened.
sts0_jobsqueued
Specifies the number of server print jobs spooled.
sts0_sopens
Specifies the number of times the server session started.
sts0_stimeout
Specifies the number of times the server session automatically disconnected.
sts0_serrorout
Specifies the number of times the server sessions failed with an error.
sts0_pwerrors
Specifies the number of server password violations.
sts0_permerrors
Specifies the number of server access permission errors.
sts0_syserrors
Specifies the number of server system errors.
sts0_bytessent_low
Specifies the number of server bytes sent to the network (low DWORD).
sts0_bytessent_high
Specifies the number of server bytes sent to the network (high DWORD).
sts0_bytesrcvd_low
Specifies the number of server bytes received from the network (low DWORD).
sts0_bytesrcvd_high
Specifies the number of server bytes received from the network (high DWORD).
sts0_avresponse
Specifies the average server response time (in milliseconds).
sts0_regbufneed
Specifies the number of times the server required a request buffer but failed to allocate one. This value indicates that the server parameters may need adjustment.
sts0_bigbuffneed
Specifies the number of times the server required a big buffer but failed to allocate one. This value indicates that the server parameters may need adjustment.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmstats.h.

See Also

Networking (Net) Overview, Net Structures, NetStatisticsGet2


STAT_WORKSTATION_0

The STAT_WORKSTATION_0 structure contains information about the specified workstation, including name, number of sessions, number of network control blocks, type of applications, and pertinent software information.

typedef struct _STAT_WORKSTATION_0 {
    DWORD          stw0_start;
    DWORD          stw0_numNCB_r;
    DWORD          stw0_numNCB_s;
    DWORD          stw0_numNCB_a;
    DWORD          stw0_fiNCB_r;
    DWORD          stw0_fiNCB_s;
    DWORD          stw0_fiNCB_a;
    DWORD          stw0_fcNCB_r;
    DWORD          stw0_fcNCB_s;
    DWORD          stw0_fcNCB_a;
    DWORD          stw0_sesstart;
    DWORD          stw0_sessfailcon;
    DWORD          stw0_sessbroke;
    DWORD          stw0_uses;
    DWORD          stw0_usefail;
    DWORD          stw0_autorec;
    DWORD          stw0_bytessent_r_lo;
    DWORD          stw0_bytessent_r_hi;
    DWORD          stw0_bytesrcvd_r_lo;
    DWORD          stw0_bytesrcvd_r_hi;
    DWORD          stw0_bytessent_s_lo;
    DWORD          stw0_bytessent_s_hi;
    DWORD          stw0_bytesrcvd_s_lo;
    DWORD          stw0_bytesrcvd_s_hi;
    DWORD          stw0_bytessent_a_lo;
    DWORD          stw0_bytessent_a_hi;
    DWORD          stw0_bytesrcvd_a_lo;
    DWORD          stw0_bytesrcvd_a_hi;
    DWORD          stw0_reqbufneed;
    DWORD          stw0_bigbufneed;
} STAT_WORKSTATION_0, *PSTAT_WORKSTATION_0, *LPSTAT_WORKSTATION_0;

Members

stw0_start
Indicates the last time (in seconds from 00:00:00, January 1,1970) the user list for servers running user-level security was modified.
stw0_numNCB_r
Indicates the last time (in seconds from 00:00:00, January 1,1970) the group list for servers running user-level security was modified.
stw0_numNCB_s
Specifies the total number of network control blocks issued by the server.
stw0_numNCB_a
Specifies the total number of network control blocks issued by applications.
stw0_fiNCB_r
Specifies the number of network control blocks that failed when issued by the redirector.
stw0_fiNCB_s
Specifies the number of network control blocks that failed when issued by the server.
stw0_fiNCB_a
Specifies the number of network control blocks that failed when issued by applications.
stw0_fcNCB_r
Specifies the number of network control blocks that were issued by the redirector and that failed before completion.
stw0_fcNCB_s
Specifies the number of network control blocks that were issued by the server and that failed before completion.
stw0_fcNCB_a
Specifies the number of network control blocks that were issued by applications and that failed before completion.
stw0_sesstart
Specifies the number of workstation sessions started.
stw0_sessfailcon
Specifies the number of workstation sessions that failed to connect, not counting those that failed due to an incorrect naming error.
stw0_sessbroke
Specifies the number of workstation sessions that failed after the session was established.
stw0_uses
Specifies how the workstation is used.
stw0_usefail
Specifies the number of workstation use failures. This is the number of times the tree connections failed, when a server is found but the resources are not found.
stw0_autorec
Specifies the number of times a workstation is used.
stw0_bytessent_r_lo
Specifies the number of workstation bytes sent to the network (low DWORD).
stw0_bytessent_r_hi
Specifies the number of workstation bytes sent to the network (high DWORD).
stw0_bytesrcvd_r_lo
Specifies the number of workstation bytes received from the network (low DWORD).
stw0_bytesrcvd_r_hi
Specifies the number of workstation bytes received from the network (high DWORD).
stw0_bytessent_s_lo
Specifies the number of server bytes sent to the network (low DWORD).
stw0_bytessent_s_hi
Specifies the number of server bytes sent to the network (high DWORD).
stw0_bytesrcvd_s_lo
Specifies the number of workstation bytes received from the network (low DWORD).
stw0_bytesrcvd_s_hi
Specifies the number of workstation bytes received from the network (high DWORD).
stw0_bytessent_a_lo
Specifies the number of application bytes sent to the network (low DWORD).
stw0_bytessent_a_hi
Specifies the number of application bytes sent to the network (high DWORD).
stw0_bytesrcvd_a_lo
Specifies the number of application bytes received from the network (low DWORD).
stw0_bytesrcvd_a_hi
Specifies the number of application bytes received from the network (high DWORD).
stw0_reqbufneed
Specifies the number of times the workstation required a request buffer but failed to allocate one. This element indicates that the workstation parameters may need adjustment.
stw0_bigbufneed
Specifies the number of times the workstation required a big buffer but failed to allocate one. This element indicates that the workstation parameters may need adjustment.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmstats.h.

See Also

Networking (Net) Overview, Net Structures, NetStatisticsGet2


STD_ALERT

The STD_ALERT structure contains information about the time and date of an event, the type of event, and the application that is raising the alert message.

typedef struct _STD_ALERT {
    DWORD  alrt_timestamp;
    TCHAR  alrt_eventname[EVLEN + 1];
    TCHAR  alrt_servicename[SNLEN + 1];
}STD_ALERT, *PSTD_ALERT, *LPSTD_ALERT;

Members

alrt_timestamp
Indicates the time and date of the event.
alrt_eventname
A Unicode string specifying the alert class (type of event).
alrt_servicename
A Unicode string specifying which application is raising the alert message.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.

See Also

Networking (Net) Overview, Net Structures, NetAlertRaise


TIME_OF_DAY_INFO

The TIME_OF_DAY_INFO structure returns information about the time of day from a remote server.

typedef struct _TIME_OF_DAY_INFO {
    DWORD      tod_elapsedt;
    DWORD      tod_msecs;
    DWORD      tod_hours;
    DWORD      tod_mins;
    DWORD      tod_secs;
    DWORD      tod_hunds;
    LONG       tod_timezone;
    DWORD      tod_tinterval;
    DWORD      tod_day;
    DWORD      tod_month;
    DWORD      tod_year;
    DWORD      tod_weekday;
} TIME_OF_DAY_INFO, *PTIME_OF_DAY_INFO, *LPTIME_OF_DAY_INFO;

Members

tod_elapsedt
Specifies the number of seconds since 00:00:00, January 1, 1970.
tod_msecs
Specifies the number of milliseconds from an arbitrary starting point (system reset). Typically, this member is read twice, once at the start of a process and again at the end, then subtracting one value from the other to determine how long the process took.
tod_hours
Specifies the current hour (0-23).
tod_mins
Specifies the current minute (0-59).
tod_secs
Specifies the current second (0-59).
tod_hunds
Specifies the current hundredth second (0.01 second) (0-99).
tod_timezone
Specifies the time zone of the server. This value is calculated, in minutes, from Greenwich Mean Time (GMT). For time zones west of Greenwich, the value is positive; for time zones east of Greenwich, the value is negative. A value of -1 indicates that the time zone is undefined.
tod_interval
Specifies the time interval for each tick of the clock. Each integral integer represents one ten-thousandth second (0.0001 second).
tod_day
Specifies the day of the month (1-31).
tod_month
Specifies the month of the year (1-12).
tod_year
Specifies the year.
tod_weekday
Specifies the day of the week (0-6, where 0 is Sunday, 1 is Monday, and so on).

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmremutl.h.

See Also

Networking (Net) Overview, Net Structures, NetRemoteTOD


USE_INFO_0

The USE_INFO_0 structure contains status information about a remote or local resource.

typedef struct _USE_INFO_0 {
    LPTSTR  ui0_local;
    LPTSTR  ui0_remote;
}USE_INFO_0, *PUSE_INFO_0, *LPUSE_INFO_0;

Members

ui0_local
Specifies a Unicode string that contains the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string.
ui0_remote
Points to a Unicode string that specifies the share name of the remote resource. The string is in the form
\\servername\sharename

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.

See Also

Networking (Net) Overview, Net Structures, NetUseEnum, NetUseGetInfo


USE_INFO_1

The USE_INFO_1 structure contains status information about a remote or shared resource and their associated accounts.

typedef struct _USE_INFO_1 {
    LPTSTR  ui1_local;
    LPTSTR  ui1_remote;
    LPTSTR  ui1_password;
    DWORD   ui1_status;
    DWORD   ui1_asg_type;
    DWORD   ui1_refcount;
    DWORD   ui1_usecount;
}USE_INFO_1, *PUSE_INFO_1, *LPUSE_INFO_1;

Members

ui1_local
Specifies a Unicode string that contains the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string.
ui1_remote
Points to a Unicode string that specifies the share name of the remote resource. The string is in the form
\e\eservername\e\esharename
ui1_password
Points to a Unicode string that contains the password needed to establish a session with a specific workstation.
ui1_status
Specifies the status of the connection. This element is not used by the NetUseAdd function. The following values are defined:
Value | Meaning
USE_OK | The connection is valid.
USE_PAUSED | Paused by local workstation.
USE_SESSLOST | Disconnected.
USE_DISCONN | An error occurred.
USE_NETERR | A network error occurred.
USE_CONN | Connection is being made.
SE_RECONN | Reconnecting.

ui1_asg_type
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
USE_WILDCARD | Matches the type of the server's shared resources. Wildcards can be used only with the NetUseAdd function, and only when the ui1_local member is a null string.
USE_DISKDEV | Disk device.
USE_SPOOLDEV | Spooled printer.
USE_CHARDEV | Communication device.
USE_IPC | Interprocess communication (IPC).

ui1_refcount
Specifies how many files, directories, and other processes are open on the remote resource. This element is not used by the NetUseAdd function.
ui1_usecount
Specifies how many explicit connections (redirection with a local device name) or implicit UNC connections (redirection without a local device name) are established with the resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.

See Also

Networking (Net) Overview, Net Structures, NetUseAdd, NetUserEnum, NetUseGetInfo


USE_INFO_2

The USE_INFO_2 structure contains usability information about a remote or shared resource and their associated accounts.

typedef struct _USE_INFO_2 {
    LPTSTR  ui2_local;
    LPTSTR  ui2_remote;
    LPTSTR  ui2_password;
    DWORD   ui2_status;
    DWORD   ui2_asg_type;
    DWORD   ui2_refcount;
    DWORD   ui2_usecount;
    LPTSTR   ui2_username;
    LPTSTR   ui2_domainname;
}USE_INFO_2, *PUSE_INFO_2, *LPUSE_INFO_2;

Members

ui2_local
Specifies a Unicode string that contains the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string.
ui2_remote
Points to a Unicode string that specifies the share name of the remote resource. The string is in the form
\\servername\sharename
ui2_password
Points to a Unicode string that contains the password needed to establish a session with a specific workstation.
ui2_status
Specifies the status of the connection. This element is not used by the NetUseAdd function. The following values are defined:
Value | Meaning
USE_OK | The connection is successful.
USE_PAUSED | Paused by a local workstation.
USE_SESSLOST | The connection is connected.
USE_DISCONN | An error occurred.
USE_NETERR | A network error occurred.
USE_CONN | The connection is being made.
SE_RECONN | Reconnecting.

ui2_asg_type
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
USE_WILDCARD | Matches the type of the server's shared resources. Wildcards can be used only with the NetUseAdd function, and only when the ui2_local member is a null string.
USE_DISKDEV | Disk device.
USE_SPOOLDEV | Spooled printer.
USE_CHARDEV | Communication device.
USE_IPC | Interprocess communication (IPC).

ui2_refcount
Specifies the number of files, directories, and other processes that are open on the remote resource. This element is not used by the NetUseAdd function.
ui2_usecount
Specifies the number of explicit connections (redirection with a local device name) or implicit UNC connections (redirection without a local device name) that are established with the resource.
ui2_username
Specifies the name of user in the domain.
ui2_domainname
Specifies the domain of the resource.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmuse.h.

See Also

Networking (Net) Overview, Net Structures, NetUseAdd, NetUserEnum, NetUseGetInfo


USER_INFO_0

The USER_INFO_0 structure specifies information about a user account.

typedef struct _USER_INFO_0 {
    LPWSTR    usri0_name;
}USER_INFO_0, *PUSER_INFO_0, *LPUSER_INFO_0;

Members

usri0_name
Specifies the name of the user account. For the NetUserSetInfo function, this member specifies the new name of the user. The number of characters in the name cannot exceed the value of UNLEN.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUseDel, NetUserEnum, NetUserSetInfo


USER_INFO_1

The USER_INFO_1 structure specifies information about a user account.

typedef struct _USER_INFO_1 {
    LPWSTR    usri1_name;
    LPWSTR    usri1_password;
    DWORD     usri1_password_age;
    DWORD     usri1_priv;
    LPWSTR    usri1_home_dir;
    LPWSTR    usri1_comment;
    DWORD     usri1_flags;
    LPWSTR    usri1_script_path;
}USER_INFO_1, *PUSER_INFO_1, *LPUSER_INFO_1;

Members

usri1_name
Specifies the name of the user account. For the NetUserSetInfo function, this member is ignored.
usri1_password
The password of the user specified in the usri1_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security. By convention, Windows NT limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT server using the account.
usri1_password_age
Specifies the number of seconds have elapsed since the usri1_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri1_priv
One of three values specifying the level of privilege assigned the usri1_name member. For the NetUserAdd function, this member must be USER_PRIV_USER. For the NetUserSetInfo function, this member must be the value returned from NetUserGetInfo or NetUserEnum. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri1_home_dir
Points to a Unicode string containing the path of the home directory for the user specified in the user_name member. The string can be null.
usri1_comment
Points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri1_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for an Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for an Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri1_script_path
Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserSetInfo


USER_INFO_2

The USER_INFO_2 structure contains user information for network accounts.

typedef struct _USER_INFO_2 {
    LPWSTR    usri2_name;
    LPWSTR    usri2_password;
    DWORD     usri2_password_age;
    DWORD     usri2_priv;
    LPWSTR    usri2_home_dir;
    LPWSTR    usri2_comment;
    DWORD     usri2_flags;
    LPWSTR    usri2_script_path;
    DWORD     usri2_auth_flags;
    LPWSTR    usri2_full_name;
    LPWSTR    usri2_usr_comment;
    LPWSTR    usri2_parms;
    LPWSTR    usri2_workstations;
    DWORD     usri2_last_logon;
    DWORD     usri2_last_logoff;
    DWORD     usri2_acct_expires;
    DWORD     usri2_max_storage;
    DWORD     usri2_units_per_week;
    PBYTE     usri2_logon_hours;
    DWORD     usri2_bad_pw_count;
    DWORD     usri2_num_logons;
    LPWSTR    usri2_logon_server;
    DWORD     usri2_country_code;
    DWORD     usri2_code_page;
}USER_INFO_2, *PUSER_INFO_2, *LPUSER_INFO_2;

Members

usri2_name
Specifies the name of the user account. For NetUserSetInfo, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri2_password
The password for the user specified in the usri2_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security. By convention, Windows NT limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT server using the account.
usri2_password_age
Specifies the number of seconds elapsed since the usri2_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri2_priv
One of three values specifying the level of privilege assigned the usri2_name member. For NetUserAdd, this member must be USER_PRIV_USER. For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri2_home_dir
Points to a Unicode string containing the path of the home directory for the user specified in the user_name member. The string can be null.
usri2_comment
Points to a Unicode string that contains a comment. The string can be a null string, or it can have any number of characters before the terminating null character.
usri2_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri2_script_path
Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null.
usri2_auth_flags
Specifies an unsigned long integer that contains values that specify the user's operator privileges.

Windows NT: For Windows NT servers, the following restrictions apply:

· For NetUserAdd, this member must be zero.
· For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum.

For NetUserGetInfo or NetUserEnum, the appropriate value is returned based on the local group membership. If the user is a member of Print Operations, AF_OP_PRINT is set. If the user is a member of Server Operations, AF_OP_SERVER is set. If the user is a member of the Account Operations, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

This member can be one of the following values:
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri2_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_usr_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_parms
Points to a Unicode string that is set aside for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri2_workstations
Points to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas (,). A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri*_flags member.
usri2_last_logon
Specifies when the last logon occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri2_last_logoff
Specifies when the last logoff occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of zero means that the last logoff time is unknown. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri2_acct_expires
Specifies when the account will expire. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of TIMEQ_FOREVER indicates that the account never expires.
usri2_max_storage
Specifies the maximum amount of disk space the user can use. Use the value specified in USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri2_units_per_week
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the usri2_logon_hours member. This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored in NetUserAdd and NetUserSetInfo functions. For Windows NT services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.
usri2_logon_hours
Points to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this element for NetUserAdd calls means that there is no time restriction. A null pointer in this element for NetUserSetInfo calls means that no change is to be made.
usri2_bad_pw_count
Specifies the number of times the user tried to log on to the account using an incorrect password. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri2_num_logons
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri2_logon_server
Points to a Unicode string that contains the name of the server to which logon requests are sent. Servernames should be preceded by two backslashes (\\). When the servername is indicated by an asterisk (\\*), the logon request can be handled by any logon server. A null string indicates that requests are sent to the domain controller.

Windows NT: For Windows NT Servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.

usri2_country_code
Specifies the country code for the user's language of choice.
usri2_code_page
Specifies the code page for the user's language of choice.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserSetInfo


USER_INFO_3

The level 3 data structure is valid only to Windows NT servers and not LAN Manager 2.x servers.

typedef struct _USER_INFO_3 {
    LPWSTR    usri3_name;
    LPWSTR    usri3_password;
    DWORD     usri3_password_age;
    DWORD     usri3_priv;
    LPWSTR    usri3_home_dir;
    LPWSTR    usri3_comment;
    DWORD     usri3_flags;
    LPWSTR    usri3_script_path;
    DWORD     usri3_auth_flags;
    LPWSTR    usri3_full_name;
    LPWSTR    usri3_usr_comment;
    LPWSTR    usri3_parms;
    LPWSTR    usri3_workstations;
    DWORD     usri3_last_logon;
    DWORD     usri3_last_logoff;
    DWORD     usri3_acct_expires;
    DWORD     usri3_max_storage;
    DWORD     usri3_units_per_week;
    PBYTE     usri3_logon_hours;
    DWORD     usri3_bad_pw_count;
    DWORD     usri3_num_logons;
    LPWSTR    usri3_logon_server;
    DWORD     usri3_country_code;
    DWORD     usri3_code_page;
    DWORD     usri3_user_id;
    DWORD     usri3_primary_group_id;
    LPWSTR    usri3_profile;
    LPWSTR    usri3_home_dir_drive;
    DWORD     usri3_password_expired;
}USER_INFO_3, *PUSER_INFO_3, *LPUSER_INFO_3;

Members

usri3_name
Specifies the name of the user account. For NetUserSetInfo, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri3_password
The password for the user specified in the usri3_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security. By convention, Windows NT limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT server using the account.
usri3_password_age
Specifies the number of seconds elapsed since the usri3_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_priv
One of three values to specify the level of privilege assigned the usri3_name member. The NetUserAdd and NetUserSetInfo functions ignore this member. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri3_home_dir
Points to a Unicode string containing the path of the home directory of the user specified in user_name. The string can be null.
usri3_comment
Points to a Unicode string that contains a comment. The string can be a null string, or it can have any number of characters before the terminating null character.
usri3_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri3_script_path
Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null.
usri3_auth_flags
Specifies an unsigned long integer that contains values that specify the user's operator privileges.

Windows NT: For Windows NT servers, the NetUserAdd and NetUserSetInfo functions ignore this member.

For NetUserGetInfo or NetUserEnum, the appropriate value is returned based on the local group membership. If the user is a member of Print Operations, AF_OP_PRINT is set. If the user is a member of Server Operations, AF_OP_SERVER is set. If the user is a member of the Account Operations, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

The NetUserAdd and NetUserSetInfo functions ignore this member.

This member can be one of the following values:
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri3_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri3_usr_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri3_parms
Points to a Unicode string that is set aside for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri3_workstations
Points to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas (,). If you do not want to restrict the number of workstations, use a null string. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri*_flags member.
usri3_last_logon
Specifies when the last logon occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri3_last_logoff
Specifies when the last logoff occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of zero means that the last logoff time is unknown. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri3_acct_expires
Specifies when the account will expire. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of TIMEQ_FOREVER indicates that the account never expires.
usri3_max_storage
Specifies the maximum amount of disk space the user can use. Use the value specified in USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri3_units_per_week
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in usri3_logon_hours. This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored in NetUserAdd and NetUserSetInfo calls. For Windows NT services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.
usri3_logon_hours
Points to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this member for NetUserAdd calls means there is no time restriction. A null pointer in this member for NetUserSetInfo calls means that no change is to be made.

Note Bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for PST).

usri3_bad_pw_count
Specifies the number of times the user tried to log on to the account using an incorrect password. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri3_num_logons
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri3_logon_server
Points to a Unicode string that contains the name of the server to which logon requests are sent. Servernames should be preceded by two backslashes (\\). A servername of an asterisk (\\*) indicates that the logon request can be handled by any logon server. A null string indicates that requests are sent to the domain controller. For Windows NT Servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_country_code
Specifies the country code for the user's language of choice.
usri3_code_page
Specifies the code page for the user's language of choice.
usri3_user_id
Specifies the relative ID (RID) of the user. The RID is determined by the SAM when the user is created. It uniquely defines this user account to SAM within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_primary_group_id
Specifies the relative ID (RID) of the Primary Global Group for this user. For NetUserAdd, this member must be DOMAIN_GROUP_RID_USERS (defined in NTSEAPI.H). For NetUserSetInfo, this member must be the RID of a global group in which the user is enrolled.
usri3_profile
Specifies a path to the user's profile. This value can be a null string, a local absolute path, or a UNC path.
usri3_home_dir_drive
Specifies the drive letter assigned to the user's home directory for logon purposes.
usri3_password_expired
Determines whether the password of the user has expired. NetUserGetInfo and NetUserEnum return zero if the password has not expired (and nonzero if it has). For NetUserAdd or NetUserSetInfo, specify nonzero to indicate that the user must change password at next logon. For NetUserSetInfo, specify zero to turn off the message indicating that the user must change password at next logon . Note that you cannot specify zero to negate the expiration of a password that has already expired.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserSetInfo


USER_INFO_10

The USER_INFO_10 structure contains user information for network accounts.

typedef struct _USER_INFO_10 {
    LPWSTR    usri10_name;
    LPWSTR    usri10_comment;
    LPWSTR    usri10_usr_comment;
    LPWSTR    usri10_full_name;
}USER_INFO_10, *PUSER_INFO_10, *LPUSER_INFO_10;

Members

usri10_name
Specifies the name of the user account. For NetUserSetInfo, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri10_comment
Points to a Unicode string that contains a comment. The string can be a null string, or can have any number of characters before the terminating null character.
usri10_usr_comment
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri10_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserDel, NetUserEnum


USER_INFO_11

The USER_INFO_11 structure contains user information for network accounts.

typedef struct _USER_INFO_11 {
    LPWSTR    usri11_name;
    LPWSTR    usri11_comment;
    LPWSTR    usri11_usr_comment;
    LPWSTR    usri11_full_name;
    DWORD     usri11_priv;
    DWORD     usri11_auth_flags;
    DWORD     usri11_password_age;
    LPWSTR    usri11_home_dir;
    LPWSTR    usri11_parms;
    DWORD     usri11_last_logon;
    DWORD     usri11_last_logoff;
    DWORD     usri11_bad_pw_count;
    DWORD     usri11_num_logons;
    LPWSTR    usri11_logon_server;
    DWORD     usri11_country_code;
    LPWSTR    usri11_workstations;
    DWORD     usri11_max_storage;
    DWORD     usri11_units_per_week;
    PBYTE     usri11_logon_hours;
    DWORD     usri11_code_page;
}USER_INFO_11, *PUSER_INFO_11, *LPUSER_INFO_11;

Members

usri11_name
Specifies the name of the user account. For NetUserSetInfo, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri11_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_usr_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_priv
One of three values specifying the level of privilege assigned the usri11_name member. For NetUserAdd, this member must be USER_PRIV_USER. For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri11_auth_flags
Specifies an unsigned long integer that contains values that specify the user's operator privileges.

For Windows NT servers, the following restrictions apply; for NetUserAdd, this member must be 0. For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum.

For NetUserGetInfo or NetUserEnum, the appropriate value is returned based on the local group membership. If the user is a member of Print Operations, AF_OP_PRINT is set. If the user is a member of Server Operations, AF_OP_SERVER is set. If the user is a member of the Account Operations, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

The NetUserAdd and NetUserSetInfo functions ignore this member.

This member can be one of the following values:
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri11_password_age
Specifies the number of seconds elapsed since the usri11_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri11_home_dir
Points to a Unicode string containing the path of the home directory for the user specified in the user_name member. The string can be null.
usri11_parms
Points to a Unicode string that is set aside for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri11_last_logon
Specifies when the last logon occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri11_last_logoff
Specifies when the last logoff occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of zero means that the last logoff time is unknown. This element is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri11_bad_pw_count
Specifies the number of times the user tried to log on to this account using an incorrect password. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri11_num_logons
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown. This element is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the member uses the sum of the values.
usri11_logon_server
Points to a Unicode string that contains the name of the server to which logon requests are sent. Servernames should be preceded by two backslashes (\\). When a servername is indicated by an asterisk (\\*), the logon request can be handled by any logon server. A null string indicates that requests are sent to the domain controller. For Windows NT Servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri11_country_code
Specifies the country code for the user's language of choice.
usri11_workstations
Points to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas (,). A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri*_flags member.
usri11_max_storage
Specifies the maximum amount of disk space the user can use. Use the value specified in USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri11_units_per_week
Specifies the number of equal-length time units into which the week is divided. The usri11_units_per_week member uses these time units to compute the length of the bit string in the usri2_logon_hours member. This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored in the NetUserAdd and NetUserSetInfo functions. For Windows NT services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.
usri11_logon_hours
Points to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this member for NetUserAdd calls means that there is no time restriction. A null pointer in this element for NetUserSetInfo calls means that no change is to be made.
usri11_code_page
Specifies the code page for the user's language of choice.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserDel, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_20

The USER_INFO_20 structure contains user information for network accounts.

typedef struct _USER_INFO_20 {
    LPWSTR    usri20_name;
    LPWSTR    usri20_full_name;
    LPWSTR    usri20_comment;
    DWORD     usri20_flags;
    DWORD     usri20_user_id;
}USER_INFO_20, *PUSER_INFO_20, *LPUSER_INFO_20;

Members

usri20_name
Specifies the name of the user account. For NetUserSetInfo, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri20_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri20_comment
Points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri20_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri20_user_id
Specifies the relative ID (RID) of the user. The RID is determined by the SAM when the user is created. It uniquely defines this user account to SAM within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserSetInfo


USER_INFO_21

The USER_INFO_21 structure contains user information for network accounts.

typedef struct _USER_INFO_21 {
    BYTE    usri21_password[ENCRYPTED_PWLEN];
}USER_INFO_21, *PUSER_INFO_21, *LPUSER_INFO_21;

Members

usri21_password
Specifies a one-way encrypted LAN Manager 2.x-compatible password.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_22

The USER_INFO_22 structure contains user information for network accounts.

typedef struct _USER_INFO_22 {
    LPWSTR    usri22_name;
    BYTE      usri22_password[ENCRYPTED_PWLEN];
    DWORD     usri22_password_age;
    DWORD     usri22_priv;
    LPWSTR    usri22_home_dir;
    LPWSTR    usri22_comment;
    DWORD     usri22_flags;
    LPWSTR    usri22_script_path;
    DWORD     usri22_auth_flags;
    LPWSTR    usri22_full_name;
    LPWSTR    usri22_usr_comment;
    LPWSTR    usri22_parms;
    LPWSTR    usri22_workstations;
    DWORD     usri22_last_logon;
    DWORD     usri22_last_logoff;
    DWORD     usri22_acct_expires;
    DWORD     usri22_max_storage;
    DWORD     usri22_units_per_week;
    PBYTE     usri22_logon_hours;
    DWORD     usri22_bad_pw_count;
    DWORD     usri22_num_logons;
    LPWSTR    usri22_logon_server;
    DWORD     usri22_country_code;
    DWORD     usri22_code_page;
}USER_INFO_22, *PUSER_INFO_22, *LPUSER_INFO_22;

Members

usri22_name
Specifies the name of the user account. For the NetUserSetInfo function, this member is ignored.
usri22_password
Specifies a one-way encrypted LAN Manager 2.x-compatible password.
usri22_password_age
Specifies the number of seconds elapsed since the usri22_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri22_priv
One of three values specifying the level of privilege assigned the usri22_name member. For the NetUserAdd function, this member must be USER_PRIV_USER. For the NetUserSetInfo function, this member must be the value returned from NetUserGetInfo or NetUserEnum. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri22_home_dir
Points to a Unicode string containing the path of the home directory for the user specified in the user_name member. The string can be null.
usri22_comment
Points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously locked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

usri22_script_path
Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null.
usri22_auth_flags
Specifies an unsigned long integer that contains values that specify the user's operator privileges.

For Windows NT servers, the following restrictions apply; for NetUserAdd, this member must be zero. For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum.

For NetUsrGetInfo or NetUserEnum, the appropriate value is returned based on the local group membership. If the user is a member of Print Operations, AF_OP_PRINT is set. If the user is a member of Server Operations, AF_OP_SERVER is set. If the user is a member of the Account Operations, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

This member can be one of the following values:
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communiations operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri22_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_usr_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_parms
Points to a Unicode string that is set aside for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri22_workstations
Points to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas (,). A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri*_flags member.
usri22_last_logon
Specifies when the last logon occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. This element is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri22_last_logoff
Specifies when the last logoff occurred. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of zero means that the last logoff time is unknown. This element is ignored in NetUserAdd and NetUserSetInfo calls.This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried and the largest value is used.
usri22_acct_expires
Specifies when the account will expire. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of TIMEQ_FOREVER indicates that the account never expires.
usri22_max_storage
Specifies the maximum amount of disk space the user can use. Use the value specified in USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri22_units_per_week
Specifies the number of equal-length time units into which the week is divided. This member uses these time units to compute the length of the bit string in the usri22_logon_hours member. This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored in the NetUserAdd and NetUserSetInfo functions. For Windows NT services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.
usri22_logon_hours
Points to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this element for NetUserAdd calls means that there is no time restriction. A null pointer in this element for NetUserSetInfo calls means that no change is to be made.
usri22_bad_pw_count
Specifies the number of times the user tried to log on to this account using an incorrect password. A value of 0xFFFFFFFF indicates that the value is unknown. This member is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the largest value is used.
usri22_num_logons
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown. This element is ignored in NetUserAdd and NetUserSetInfo calls. This member is maintained separately on each Backup Domain Controller (BDC) in the domain. To get an accurate value, each BDC in the domain must be queried, and the member uses the sum of the values.
usri22_logon_server
Points to a Unicode string that contains the name of the server to which logon requests are sent. Servernames should be preceded by two backslashes (\\). When a servername is represented by an asterisk (\\*), the logon request can be handled by any logon server. A null string indicates that requests are sent to the domain controller. For Windows NT Servers, the NetUserGetInfo and NetUserEnum functions return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri22_country_code
Specifies the country code for the user's language of choice. Windows NT does not use the country code.
usri22_code_page
Specifies the code page for the user's language of choice. Windows NT does not use the code page.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_1003

The USER_INFO_1003 structure contains user information for network accounts.

typedef struct _USER_INFO_1003 {
    LPWSTR    usri1003_password;
} USER_INFO_1003, *PUSER_INFO_1003, *LPUSER_INFO_1003;

Members

usri1003_password
The password for the user specified in the usri1003_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security. By convention, Windows NT limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT server using the account.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_1005

The USER_INFO_1005 structure contains user information for network accounts.

typedef struct _USER_INFO_1005 {
    DWORD    usri1005_priv;
} USER_INFO_1005, *PUSER_INFO_1005, *LPUSER_INFO_1005;

Members

usri1005_priv
One of three values specifying the level of privilege assigned the usri1_name member. For NetUserAdd, this member must be USER_PRIV_USER. For NetUserSetInfo, this member must be the value returned from NetUserGetInfo or NetUserEnum. This member can be one of the following values:
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1006

The USER_INFO_1006 structure contains user information for network accounts.

typedef struct _USER_INFO_1006 {
    LPWSTR    usri1006_home_dir;
} USER_INFO_1006, *PUSER_INFO_1006, *LPUSER_INFO_1006;

Members

usri1006_home_dir
Points to a Unicode string containing the path of the home directory for the user specified in the user_name member. The string can be null.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1007

The USER_INFO_1007 structure contains user information for network accounts.

typedef struct _USER_INFO_1007 {
    LPWSTR    usri1007_comment;
} USER_INFO_1007, *PUSER_INFO_1007, *LPUSER_INFO_1007;

Members

usri1007_comment
Points to a Unicode string that contains a comment. This string can be a null string, or it can have any number of characters before the terminating null character.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1008

The USER_INFO_1008 structure contains user information for network accounts.

typedef struct _USER_INFO_1008 {
    DWORD    usri1008_flags;
} USER_INFO_1008, *PUSER_INFO_1008, *LPUSER_INFO_1008;

Members

usri1008_flags
Contains values that determine several features. This member can be any of the following values:
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. For NetUserSetInfo, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT: Represents the password, which should never expire on the account.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT Workstation or Windows NT Server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a Windows NT Backup Domain Controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a Windows NT domain that trusts other domains.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1009

The USER_INFO_1009 structure contains user information for network accounts.

typedef struct _USER_INFO_1009 {
    LPWSTR    usri1009_script_path;
} USER_INFO_1009, *PUSER_INFO_1009, *LPUSER_INFO_1009;

Members

usri1009_script_path
Points to a Unicode string specifying the path of the user's logon script, .CMD, .EXE, or .BAT file. The string can be null.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1010

The USER_INFO_1010 structure contains user information for network accounts.

typedef struct _USER_INFO_1010 {
    DWORD    usri1010_auth_flags;
} USER_INFO_1010, *PUSER_INFO_1010, *LPUSER_INFO_1010;

Members

usri1010_auth_flags
Specifies an unsigned long integer that contains values that specify the user's operator privileges.

Windows NT: For Windows NT servers, this member must be the value returned from NetUserGetInfo or NetUserEnum.

For NetUserGetInfo or NetUserEnum, the appropriate value is returned based on the local group membership. If the user is a member of Print Operations, AF_OP_PRINT is set. If the user is a member of Server Operations, AF_OP_SERVER is set. If the user is a member of the Account Operations, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

This member can be one of the following values:
Value | Meaning
AF_OP_PRINT | If 1, print operator privilege is enabled
AF_OP_COMM | If 1, communications operator privilege is enabled
AF_OP_SERVER | If 1, server operator privilege is enabled
AF_OP_ACCOUNTS | If 1, accounts operator privilege is enabled

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1011

The USER_INFO_1011 structure contains user information for network accounts.

typedef struct _USER_INFO_1011 {
    LPWSTR    usri1011_full_name;
} USER_INFO_1011, *PUSER_INFO_1011, *LPUSER_INFO_1011;

Members

usri1011_full_name
Points to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1012

The USER_INFO_1012 structure contains user information for network accounts.

typedef struct _USER_INFO_1012 {
    LPWSTR    usri1012_usr_comment;
} USER_INFO_1012, *PUSER_INFO_1012, *LPUSER_INFO_1012;

Members

usri1012_usr_comment
Points to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1013

The USER_INFO_1013 structure contains user information for network accounts.

typedef struct _USER_INFO_1013 {
    LPWSTR    usri1013_parms;
} USER_INFO_1013, *PUSER_INFO_1013, *LPUSER_INFO_1013;

Members

usri1013_parms
Points to a Unicode string that is set aside for use by applications. The string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information. The Windows NT components that use this member are services for Macintosh, file and print services for Netware, and the Remote Access Server (RAS).

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1014

The USER_INFO_1014 structure contains user information for network accounts.

typedef struct _USER_INFO_1014 {
    LPWSTR    usri1014_workstations;
} USER_INFO_1014, *PUSER_INFO_1014, *LPUSER_INFO_1014;

Members

usri1014_workstations
Points to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas (,). A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri*_flags member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1017

The USER_INFO_1017 structure contains user information for network accounts.

typedef struct _USER_INFO_1017 {
    DWORD    usri1017_acct_expires;
} USER_INFO_1017, *PUSER_INFO_1017, *LPUSER_INFO_1017;

Members

usri1017_acct_expires
Specifies when the account will expire. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of TIMEQ_FOREVER indicates that the account never expires.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1018

The USER_INFO_1018 structure contains user information for network accounts.

typedef struct _USER_INFO_1018 {
    DWORD    usri1018_max_storage;
} USER_INFO_1018, *PUSER_INFO_1018, *LPUSER_INFO_1018;

Members

usri1018_max_storage
Specifies the maximum amount of disk space the user can use. For Windows NT, you must use the value specified in USER_MAXSTORAGE_UNLIMITED to use all available disk space.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures


USER_INFO_1020

The USER_INFO_1020 structure contains user information for network accounts.

typedef struct _USER_INFO_1020 {
    DWORD     usri1020_units_per_week;
LPBYTE    usri1020_logon_hours;
} USER_INFO_1020, *PUSER_INFO_1020, *LPUSER_INFO_1020;

Members

usri1020_units_per_week
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in usri1020_logon_hours. This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored in NetUserAdd and NetUserSetInfo functions.

Windows NT: For Windows NT services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri1020_logon_hours
Points to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this element for NetUserAdd calls means that there is no time restriction. A null pointer in this element for NetUserSetInfo calls means that no change is to be made.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserSetInfo


USER_INFO_1023

The USER_INFO_1023 structure contains user information for network accounts.

typedef struct _USER_INFO_1023 {
    LPWSTR    usri1023_logon_server;
} USER_INFO_1023, *PUSER_INFO_1023, *LPUSER_INFO_1023;

Members

usri1023_logon_server
Points to a Unicode string that contains the name of the server to which logon requests are sent. Servernames should be preceded by two backslashes (\\). When a servername is represented by an asterisk (\\*), the logon request can be handled by any logon server. A null string indicates that requests are sent to the domain controller.

Windows NT: For Windows NT Servers, the NetUserGetInfo and NetUserEnum functions return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserAdd, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_1024

The USER_INFO_1024 structure contains user information for network accounts.

typedef struct _USER_INFO_1024 {
    DWORD    usri1024_country_code;
} USER_INFO_1024, *PUSER_INFO_1024, *LPUSER_INFO_1024;

Members

usri1024_country_code
Specifies the country code for the user's language of choice. Windows NT does not use the country code.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1025

The USER_INFO_1025 structure contains user information for network accounts.

typedef struct _USER_INFO_1025 {
    DWORD    usri1025_code_page;
} USER_INFO_1025, *PUSER_INFO_1025, *LPUSER_INFO_1025;

Members

usri1025_code_page
Specifies the code page for the user's language of choice. Windows NT does not use the code page.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures


USER_INFO_1051

The USER_INFO_1051 structure contains user information for network accounts.

typedef struct _USER_INFO_1051 {
    DWORD    usri1051_primary_group_id;
} USER_INFO_1051, *PUSER_INFO_1051, *LPUSER_INFO_1051;

Members

usri1051_primary_group_id
Specifies the relative ID (RID) of the Primary Global Group for this user. For the NetUserAdd function, this member must be DOMAIN_GROUP_RID_USERS (defined in the NTSEAPI.H file). For the NetUserSetInfo function, this member must be the RID of a global group that represents the enrolled user.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_INFO_1052

The USER_INFO_1052 structure contains user information for network accounts.

typedef struct _USER_INFO_1052 {
    LPWSTR    usri1052_profile;
} USER_INFO_1052, *PUSER_INFO_1052, *LPUSER_INFO_1052;

Members

usri1052_profile
Specifies a path to the user's profile. This value can be a null string, a local absolute path, or a UNC path.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures


USER_INFO_1053

The USER_INFO_1053 structure contains user information for network accounts.

typedef struct _USER_INFO_1053 {
    LPWSTR    usri1053_home_dir_drive;
} USER_INFO_1053, *PUSER_INFO_1053, *LPUSER_INFO_1053;

Members

usri1053_home_dir_drive
Specifies the drive letter assigned to the user's home directory for logon purposes.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserSetInfo


USER_MODALS_INFO_0

The USER_MODALS_INFO_0 structure contains information about users and global groups in a security database.

typedef struct _USER_MODALS_INFO_0 {
    DWORD    usrmod0_min_passwd_len;
    DWORD    usrmod0_max_passwd_age;
    DWORD    usrmod0_min_passwd_age;
    DWORD    usrmod0_force_logoff;
    DWORD    usrmod0_password_hist_len;
}USER_MODALS_INFO_0, *PUSER_MODALS_INFO_0, *LPUSER_MODALS_INFO_0;

Members

usrmod0_min_passwd_len
Specifies the minimum allowable password length. Valid values for this element are zero through PWLEN.
usrmod0_max_passwd_age
Specifies, in seconds, the maximum allowable password age. A value of TIMEQ_FOREVER indicates that the password never expires. The minimum valid value for this element is ONE_DAY. The value specified must be greater than or equal to the value for the usrmod0_min_passwd_age member.
usrmod0_min_passwd_age
Specifies, in seconds, the minimum elapsed time between when the password was last changed and when it can be changed again. A value of zero indicates that no delay is required between password updates. The value specified must be less than or equal to the value for the usrmod0_max_passwd_age member.
usrmod0_force_logoff
Specifies, in seconds, the amount of time between the end of the valid logon time and the time when the user is forced to log off the network. A value of TIMEQ_FOREVER indicates that the user is never forced to log off. A value of zero indicates that the user will be forced to log off immediately when the valid logon time expires.
usrmod0_password_hist_len
Specifies the length of password history maintained. A new password cannot match any of the previous usrmod0_password_hist_len passwords. Valid values for this element are zero through DEF_MAX_PWHIST.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_1

The USER_MODALS_INFO_1 structure contains information about the role and primary use of logon servers in a security database.

typedef struct _USER_MODALS_INFO_1 {
    DWORD    usrmod1_role;
    LPWSTR   usrmod1_primary;
}USER_MODALS_INFO_1, *PUSER_MODALS_INFO_1, *LPUSER_MODALS_INFO_1;

Members

usrmod1_role
Specifies the role of the logon server. The following values are defined:
Value | Meaning
UAS_ROLE_STANDALONE | The logon server is a stand-alone server.
UAS_ROLE_MEMBER | The logon server is a member.
UAS_ROLE_BACKUP | The logon server is a backup.
UAS_ROLE_PRIMARY | The logon server is a domain controller.

If the Netlogon service is not being used, the element should be set to UAS_ROLE_STANDALONE.

usrmod1_primary
A Unicode string that specifies the name of the domain controller that stores the primary copy of the database for the user account manager.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_2

The USER_MODALS_INFO_2 structure contains information about domains in a security database.

typedef struct _USER_MODALS_INFO_2 {
    LPWSTR  usrmod2_domain_name;
    PSID    usrmod2_domain_id;
}USER_MODALS_INFO_2, *PUSER_MODALS_INFO_2, *LPUSER_MODALS_INFO_2;

Members

usrmod2_domain_name
Specifies the name of the Security Account Manager (SAM) domain. For a domain controller, this is the name of the domain that the controller is a member of. For Windows NT Workstations, this is the name of the computer.
usrmod2_domain_id
A Unicode string that specifies the domain security identifier of the domain named by the usrmod2_domain_name member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_3

The USER_MODALS_INFO_3 structure contains lockout information about users and global groups in a security database.

typedef struct _USER_MODALS_INFO_3 {
    DWORD   usrmod3_lockout_duration;
    DWORD   usrmod3_lockout_observation_window;
    DWORD   usrmod3_lockout_threshold;
}USER_MODALS_INFO_3, *PUSER_MODALS_INFO_3, *LPUSER_MODALS_INFO_3;

Members

usrmod3_lockout_duration
Indicates, in seconds, how long a locked account will remain locked before being automatically unlocked.
usrmod3_lockout_observation_window
Specifies the maximum time, in seconds, between any two failed logon attempts for lockout to occur.
usrmod3_lockout_threshold
Specifies the number of invalid password authentications for which an account is to be marked as locked out.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_1001

The USER_MODALS_INFO_1001 structure contains mimimum length of passwords in a security database.

typedef struct _USER_MODALS_INFO_1001 {
    DWORD    usrmod1001_min_passwd_len;
}USER_MODALS_INFO_1001, *PUSER_MODALS_INFO_1001, *LPUSER_MODALS_INFO_1001;

Members

usrmod1001_min_passwd_len
Specifies the minimum allowable password length. Valid values for this element are zero through PWLEN.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1002

The USER_MODALS_INFO_1002 structure contains maximum duration of passwords in a security database.

typedef struct _USER_MODALS_INFO_1002 {
    DWORD    usrmod1002_max_passwd_age;
}USER_MODALS_INFO_1002, *PUSER_MODALS_INFO_1002, *LPUSER_MODALS_INFO_1002;

Members

usrmod1002_max_passwd_age
Specifies, in seconds, the maximum allowable password age. A value of TIMEQ_FOREVER indicates that the password never expires. The minimum valid value for this element is ONE_DAY. The value specified must be greater than or equal to the value for the usrmod1002_min_passwd_age member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1003

The USER_MODALS_INFO_1003 structure contains the duration of passwords for users and global groups in a security database.

typedef struct _USER_MODALS_INFO_1003 {
    DWORD    usrmod1003_min_passwd_age;
}USER_MODALS_INFO_1003, *PUSER_MODALS_INFO_1003, *LPUSER_MODALS_INFO_1003;

Members

usrmod1003_min_passwd_age
Specifies the minimum allowable password age. Valid values for this element are zero through PWLEN.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1004

The USER_MODALS_INFO_1004 structure contains logoff information about users and global groups in a security database.

typedef struct _USER_MODALS_INFO_1004 {
    DWORD    usrmod1004_force_logoff;
}USER_MODALS_INFO_1004, *PUSER_MODALS_INFO_1004, *LPUSER_MODALS_INFO_1004;

Members

usrmod1004_force_logoff
Specifies, in seconds, the amount of time between the end of the valid logon time and the time when the user is forced to log off the network. A value of TIMEQ_FOREVER indicates that the user is never forced to log off. A value of zero indicates that the user will be forced to log off immediately when the valid logon time expires.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1005

The USER_MODALS_INFO_1005 structure contains password history information about users and global groups in a security database.

typedef struct _USER_MODALS_INFO_1005 {
    DWORD    usrmod1005_password_hist_len;
}USER_MODALS_INFO_1005, *PUSER_MODALS_INFO_1005, *LPUSER_MODALS_INFO_1005;

Members

usrmod1005_password_hist_len
Specifies the length of password history that the system maintains. A new password cannot match any of the previous usrmod1001_password_hist_len passwords. Valid values for this element are zero through DEF_MAX_PWHIST.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1006

The USER_MODALS_INFO_1006 structure contains the various roles of logon servers in a security database.

typedef struct _USER_MODALS_INFO_1006 {
     DWORD   usrmod1006_role;
} USER_MODALS_INFO_1006, *PUSER_MODALS_INFO_1006, *LPUSER_MODALS_INFO_1006;

Members

usrmod1006_role
Specifies the role of the logon server as one of the following possible values:
Value | Meaning
UAS_ROLE_STANDALONE | Logon server is a stand-alone. Use this value if no logon services are available
UAS_ROLE_MEMBER | Logon server is a member.
UAS_ROLE_BACKUP | Logon server is a backup.
UAS_ROLE_PRIMARY | Logon server is a domain controller.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_MODALS_INFO_1007

The USER_MODALS_INFO_1007 structure contains user account information about the domain controller in a security database.

typedef struct _USER_MODALS_INFO_1007 {
     LPWSTR  usrmod1007_primary;
} USER_MODALS_INFO_1007, *PUSER_MODALS_INFO_1007, *LPUSER_MODALS_INFO_1007;

Members

usrmod1007_primary
A Unicode string that specifies the name of the domain controller that stores the primary copy of the database for the user account manager.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmaccess.h.

See Also

Networking (Net) Overview, Net Structures, NetUserModalsSet


USER_OTHER_INFO

The USER_OTHER_INFO structure contains user error code information in the alert error codes.

typedef struct _USER_OTHER_INFO {
    DWORD  alrtus_errcode;
    DWORD  alrtus_numstrings;
}USER_OTHER_INFO, *PUSER_OTHER_INFO, *LPUSER_OTHER_INFO;

Members

alrtus_errcode
Specifies the error code for the new message in the message log.
alrtus_numstrings
Specifies the number (0-9) of consecutive Unicode strings in the message log.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmalert.h.

See Also

Networking (Net) Overview, Net Structures, NetAlertRaise


WKSTA_INFO_100

The WKSTA_INFO_100 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_100 {
    DWORD     wki100_platform_id;
    LPWSTR    wki100_computername;
    LPWSTR    wki100_langroup;
    DWORD     wki100_ver_major;
    DWORD     wki100_ver_minor;
}WKSTA_INFO_100, *PWKSTA_INFO_100, *LPWKSTA_INFO_100;

Members

wki100_platform_id
Indicates the information level to use to retrieve platform-specific information.
wki100_computername
Points to a Unicode string containing the name of the local computer.
wki100_langroup
Points to a Unicode string containing the name of the domain to which the computer belongs.
wki100_ver_major
Specifies the major version number of the operating system running on the computer.
wki100_ver_minor
Specifies the minor version number of the operating system running on the computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_101

The WKSTA_INFO_101 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_101 {
    DWORD     wki101_platform_id;
    LPWSTR    wki101_computername;
    LPWSTR    wki101_langroup;
    DWORD     wki101_ver_major;
    DWORD     wki101_ver_minor;
    LPWSTR    wki101_lanroot;
}WKSTA_INFO_101, *PWKSTA_INFO_101, *LPWKSTA_INFO_101;

Members

wki101_platform_id
Indicates the information level to use to retrieve platform-specific information.
wki101_computername
Points to a Unicode string containing the name of the local computer.
wki101_langroup
Points to a Unicode string containing the name of the domain to which the computer belongs.
wki101_ver_major
Specifies the major version number of the operating system running on the computer.
wki101_ver_minor
Specifies the minor version number of the operating system running on the computer.
wki101_lanroot
Points to a Unicode string that contains the path to the LANMAN directory.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_102

The WKSTA_INFO_102 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_102 {
    DWORD     wki102_platform_id;
    LPWSTR    wki102_computername;
    LPWSTR    wki102_langroup;
    DWORD     wki102_ver_major;
    DWORD     wki102_ver_minor;
    LPWSTR    wki102_lanroot;
    DWORD     wki102_logged_on_users;
}WKSTA_INFO_102, *PWKSTA_INFO_102, *LPWKSTA_INFO_102;

Members

wki102_platform_id
Indicates the information level to use to retrieve platform-specific information.
wki102_computername
Points to a Unicode string containing the name of the local computer.
wki102_langroup
Points to a Unicode string containing the name of the domain to which the computer belongs.
wki102_ver_major
Specifies the major version number of the operating system running on the computer.
wki102_ver_minor
Specifies the minor version number of the operating system running on the computer.
wki102_lanroot
Points to a Unicode string that contains the path to the LANMAN directory.
wki102_logged_on_users
Returns the number of users who are logged on to the local computer.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_302

The WKSTA_INFO_302 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_302{
    DWORD     wki302_char_wait;
    DWORD     wki302_collection_time;
    DWORD     wki302_maximum_collection_count;
    DWORD     wki302_keep_conn;
    DWORD     wki302_keep_search;
    DWORD     wki302_max_cmds;
    DWORD     wki302_num_work_buf;
    DWORD     wki302_siz_work_buf;
    DWORD     wki302_max_wrk_cache;
    DWORD     wki302_sess_timeout;
    DWORD     wki302_siz_error;
    DWORD     wki302_num_alerts;
    DWORD     wki302_num_services;
    DWORD     wki302_errlog_sz;
    DWORD     wki302_print_buf_time;
    DWORD     wki302_num_char_buf;
    DWORD     wki302_siz_char_buf;
    LPWSTR    wki302_wrk_heuristics;
    DWORD     wki302_mailslots;
    DWORD     wki302_num_dgram_buf;
}WKSTA_INFO_302, *PWKSTA_INFO_302, *LPWKSTA_INFO_302;

Members

wki302_char_wait
Specifies the number of seconds the computer will wait for a remote resource to become available.
wki302_collection_time
Specifies the number of milliseconds the computer will collect data before sending the data to a character device resource. The workstation waits the specified time or collects the number of characters specified by wki302_maximum_collection_count, whichever comes first.
wki302_maximum_collection_count
Specifies the number of bytes of information the computer will collect before sending the data to a character device resource. The workstation collects the specified number of bytes or waits the time specified by wki302_collection_time, whichever comes first.
wki302_keep_conn
Specifies the number of seconds the server will maintain an inactive connection to a resource.
wki302_keep_search
Defines the number of seconds an inactive search will continue.
wki302_max_cmds
Specifies the number of simultaneous network device driver commands that can be sent to the network.
wki302_num_work_buf
Specifies the number of internal buffers the computer has.
wki302_siz_work_buf
Specifies the size, in bytes, of each internal buffer.
wki302_max_wrk_cache
Specifies the maximum size, in bytes, of an internal cache buffer.
wki302_sess_timeout
Indicates the number of seconds the server waits before disconnecting an inactive session.
wki302_siz_error
Specifies the size, in bytes, of an internal error buffer.
wki302_num_alerts
Specifies the maximum number of clients that can receive alert messages. (This member is not supported under MS-DOS.) The Alerter service registers at least three clients when it begins to run.
wki302_num_services
Specifies the number of services that can be installed on the computer at any time.
wki302_errlog_sz
Specifies the maximum size, in kilobytes, of the client's error log file.
wki302_print_buf_time
Specifies the number of seconds the server waits before closing inactive compatibility-mode print jobs.
wki302_num_char_buf
Specifies the number of character pipe buffers and device buffers the client can have.
wki302_siz_char_buf
Specifies the maximum size, in bytes, of a character pipe buffer and device buffer.
wki302_wrk_heuristics
Points to a Unicode string of flags used to control a client's operation.
wki302_mailslots
Specifies the maximum number of mailslots allowed.
wki302_num_dgram_buf
Specifies the number of buffers to allocate for receiving datagrams.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_402

The WKSTA_INFO_402 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_402{
    DWORD     wki402_char_wait;
    DWORD     wki402_collection_time;
    DWORD     wki402_maximum_collection_count;
    DWORD     wki402_keep_conn;
    DWORD     wki402_keep_search;
    DWORD     wki402_max_cmds;
    DWORD     wki402_num_work_buf;
    DWORD     wki402_siz_work_buf;
    DWORD     wki402_max_wrk_cache;
    DWORD     wki402_sess_timeout;
    DWORD     wki402_siz_error;
    DWORD     wki402_num_alerts;
    DWORD     wki402_num_services;
    DWORD     wki402_errlog_sz;
    DWORD     wki402_print_buf_time;
    DWORD     wki402_num_char_buf;
    DWORD     wki402_siz_char_buf;
    LPWSTR    wki402_wrk_heuristics;
    DWORD     wki402_mailslots;
    DWORD     wki402_num_dgram_buf;
    DWORD     wki402_max_threads;
}WKSTA_INFO_402, *PWKSTA_INFO_402, *LPWKSTA_INFO_402;

Members

wki402_char_wait
Specifies the number of seconds the computer will wait for a remote resource to become available.
wki402_collection_time
Specifies the number of milliseconds the computer will collect data before sending the data to a character device resource. The workstation waits the specified time or collects the number of characters specified by wki402_maximum_collection_count, whichever comes first.
wki402_maximum_collection_count
Specifies the number of bytes of information the computer will collect before sending the data to a character device resource. The workstation collects the specified number of bytes or waits the time specified by the wki0_chartime member, whichever comes first.
wki402_keep_conn
Specifies the number of seconds the server will maintain an inactive connection to a server's resource.
wki402_keep_search
Defines the number of seconds an inactive search will continue.
wki402_max_cmds
Specifies the number of simultaneous network device driver commands that can be sent to the network.
wki402_num_work_buf
Specifies the number of internal buffers the computer has.
wki402_siz_work_buf
Specifies the size, in bytes, of each internal buffer.
wki402_max_wrk_cache
Specifies the maximum size, in bytes, of an internal cache buffer.
wki402_sess_timeout
Indicates the number of seconds the server waits before disconnecting an inactive session.
wki402_siz_error
Specifies the size, in bytes, of an internal error buffer.
wki402_num_alerts
Specifies the maximum number of clients that can receive alert messages. (This member is not supported under MS-DOS.) The Alerter service registers at least three clients when it begins to run.
wki402_num_services
Specifies the number of services that can be installed on the computer at any time.
wki402_errlog_sz
Specifies the maximum size, in kilibytes, of the client's error log file.
wki402_print_buf_time
Specifies the number of seconds the server waits before closing inactive compatibility-mode print jobs.
wki402_num_char_buf
Specifies the number of character pipe buffers and device buffers the client can have.
wki402_siz_char_buf
Specifies the maximum size, in bytes, of a character pipe buffer and device buffer.
wki402_wrk_heuristics
Points to a Unicode string of flags used to control a client's operation.
wki402_mailslots
Specifies the maximum number of mailslots allowed.
wki402_num_dgram_buf
Specifies the number of buffers to allocate for receiving datagrams.
wki402_max_threads
Specifies the number of threads the computer can dedicate to the network.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_TRANSPORT_INFO_0

The WKSTA_TRANSPORT_INFO_0 structure contains information about the workstation transport protocol, such as Wide Area Net (WAN) or NetBIOS.

typedef struct _WKSTA_TRANSPORT_INFO_0 {
    DWORD     wkti0_quality_of_service;
    DWORD     wkti0_number_of_vcs;
    LPWSTR    wkti0_transport_name;
    LPWSTR    wkti0_transport_address;
    BOOL      wkti0_wan_ish;
}WKSTA_TRANSPORT_INFO_0, *PWKSTA_TRANSPORT_INFO_0, *LPWKSTA_TRANSPORT_INFO_0;

Members

wkti0_quality_of_service
Supplies a value that specifies the search order of the transport protocol with respect to other transport protocols. The highest value is searched first.
wkti0_number_of_vcs
Specifies the number of clients communicating with the server using this transport protocol.
wkti0_transport_name
Specifies the device name of the transport protocol.
wkti0_transport_address
Specifies the address of the server on this transport protocol.
wkti0_wan_ish
This member is ignored by the NetWkstaTransportAdd function. For the NetWkstaTransportEnum function, this member indicates that this transport protocol is a WAN transport protocol. This member is set TRUE for NetBIOS/TCIP; it is set FALSE for Net/BEUI and NetBIOS/IPX.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaTransportAdd, NetWkstaTransportEnum


WKSTA_USER_INFO_0

The WKSTA_USER_INFO_0 structure contains the name of the users on a specified workstation.

typedef struct _WKSTA_USER_INFO_0 {
    LPWSTR    wkui0_username;
}WKSTA_USER_INFO_0, *PWKSTA_USER_INFO_0, *LPWKSTA_USER_INFO_0;

Members

wkui0_username
Returns the name of the user currently logged on to the workstation.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaUserEnum, NetWkstaUserGetInfo, NetWkstaUserSetInfo


WKSTA_USER_INFO_1

The WKSTA_USER_INFO_1 structure contains user information about a specified workstation, including the name of the current user, the operating system domains accessed by the workstation, and user account information.

typedef struct _WKSTA_USER_INFO_1 {
    LPWSTR    wkui1_username;
    LPWSTR    wkui1_logon_domain;
    LPWSTR    wkui1_oth_domains;
    LPWSTR    wkui1_logon_server;
}WKSTA_USER_INFO_1, *PWKSTA_USER_INFO_1, *LPWKSTA_USER_INFO_1;

Members

wkui1_username
Returns the name of the user currently logged on to the workstation.
wkui1_logon_domain
Returns the domain name of the user account of the user currently logged on to the workstation.
wkui1_oth_domains
Returns the list of other operating system domains browsed by the workstation. The domain names are separated by blanks.
wkui1_logon_server
Returns the name of the computer that authenticated the server.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaUserEnum, NetWkstaUserGetInfo, NetWkstaUserSetInfo


WKSTA_USER_INFO_1101

The WKSTA_USER_INFO_1101 structure contains user information about the operating system domains accessed by a workstation.

typedef struct _WKSTA_USER_INFO_1101 {
    LPWSTR    wkui1101_oth_domains;
} WKSTA_USER_INFO_1101, *PWKSTA_USER_INFO_1101, *LPWKSTA_USER_INFO_1101;

Members

wkui1101_oth_domains
Returns the list of other operating system domains browsed by this workstation. The domain names are separated by blanks.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in lmwksta.h.

See Also

Networking (Net) Overview, Net Structures, NetWkstaUserGetInfo, NetWkstaUserSetInfo


Remote Access Service (RAS)

Remote Access Service (RAS) lets users at remote locations work as if connected directly to a computer network, accessing one or more RAS servers.


About Remote Access Service

Microsoft® Windows® enables RAS client applications to perform the following tasks.

  • Display any of the RAS common dialog boxes. This includes the main Dial-Up Networking dialog box, the Dial-Up Networking Monitor property sheet, and other dialog boxes for creating, editing, copying, or dialing a phone-book entry.
  • Start and end a RAS connection operation using the common dialog boxes or the low-level dialing functions.
  • Create, edit, or copy phone-book entries using the common dialog boxes or the low-level phone-book functions.
  • Work with entries in the RAS AutoDial mapping database, which maps network addresses to the phone-book entry that can establish a connection to the address.
  • Get RAS information, including information about existing RAS connections, information about the RAS-capable devices configured on the local computer, and notifications when a RAS connection begins or ends.

Windows NT version 4.0 also provides support for RAS server administration and for third-party extensions to RAS server security and connection management. Windows 95 does not provide RAS server support.


RAS Common Dialog Boxes

Windows NT version 4.0 provides a set of functions that display the RAS dialog boxes provided by the system. These functions make it easy for applications to display a familiar user interface so users can perform RAS tasks, such as establishing and monitoring connections, or working with phone-book entries. Windows 95 does not currently support these functions.

The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. From this dialog box, the user can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user preferences. The RasPhonebookDlg function uses the RASPBDLG structure to specify additional input and output parameters. For example, you can set members of the structure to control the position of the dialog box on the screen. You can use the RASPBDLG structure to specify a RasPBDlgFunc callback function that receives notifications of user activity while the dialog box is open. For example, RAS calls your RasPBDlgFunc function if the user dials, edits, creates, or deletes a phone-book entry.

You can use the RasDialDlg function to start a RAS connection operation without displaying the main Dial-Up Networking dialog box. With RasDialDlg, you specify a phone number or phone-book entry to call. The function displays a stream of dialog boxes that indicate the state of the connection operation. The RasDialDlg function uses a RASDIALDLG structure to specify additional input and output parameters, such as position of the dialog box and the phone-book subentry to call.

To display the Dial-Up Networking Monitor property sheet, call the RasMonitorDlg function. This dialog box enables the user to monitor the status of existing connections. The RasMonitorDlg function uses a RASMONITORDLG structure to specify additional input and output parameters, such as the position of the dialog box and the property sheet page to display on top.

You can call the RasEntryDlg function to display a property sheet for creating, editing, or copying a phone-book entry. The RasEntryDlg function uses a RASENTRYDLG structure to specify additional input and output parameters, such as the position of the dialog box and the type of phone book operation.


RAS Connection Operations

Windows NT version 4.0 provides the RasPhonebookDlg and RasDialDlg functions that display the built-in user interface for starting a RAS connection operation. For most applications, this is the preferred way to start a RAS connection operation. Windows 95 does not currently support these functions.

The remainder of this section describes the low-level functions for starting a RAS connection. These functions are available on both Windows NT and Windows 95.

A RAS client application uses the RasDial function to establish a connection to a RAS server. The RasDial function starts the connection operation, which is then carried out by the Remote Access Connection Manager.

The Remote Access Connection Manager is a service that handles the details of establishing the connection to the remote server. This service also provides the client with status information during the connection operation. The Remote Access Connection Manager starts automatically when an application loads the RASAPI32.DLL.

The RasDial call specifies the following information when it starts a connection operation:

  • The connection information that the Remote Access Connection Manager needs to establish the connection.
  • An optional notification handler that receives progress notifications during the connection operation. If the RasDial call specifies a notification handler, the call is asynchronous; otherwise, it is synchronous.
  • An optional RASDIALEXTENSIONS structure to enable or disable extensions to the RasDial operation. The extensions permit a RAS client to directly enable some modem settings, to control whether RAS uses the prefixes and suffixes in a phonebook entry, and to support paused states during the connection operation.


Synchronous Operations

When RasDial is invoked as a synchronous operation, the function does not return until the connection has been established or an error occurs. Synchronous mode provides a simple way for a RAS client to establish a connection. The client can simply call RasDial, wait for the function to return, and then call the RasGetConnectStatus function to determine whether the connection operation was successful. Once the connection has been established, the client application can terminate without breaking the connection. If an error occurs, the client application must shut down the connection operation before terminating.

The disadvantage of synchronous mode is that the client does not receive progress notifications as the connection operation proceeds. As a workaround for this lack of progress notifications, a synchronous mode client can use a separate thread that calls RasGetConnectStatus to poll for and display the current state. However, for RAS clients that want to receive progress information, the preferred technique is to invoke RasDial asynchronously.


Asynchronous Operations

When RasDial is invoked as an asynchronous operation, the function returns immediately. In asynchronous mode, the RasDial call must specify a notification handler that the Remote Access Connection Manager uses to inform the client whenever the connection operation changes states or an error occurs.

The notification handler can be a window to receive messages, or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function. The Remote Access Connection Manager makes its asynchronous notifications in the context of the thread that made the RasDial call. For this reason, the calling thread must not terminate until the connection operation has been successfully established or an error occurs. As in synchronous mode, the client application can safely terminate once the connection has been established, and it must shut down the connection operation if an error occurs.


Phonebook Files and Connection Information

A RasDial call must specify the information that the Remote Access Connection Manager needs to establish the connection. Typically, the RasDial call provides the connection information by specifying a phone-book entry. The connection information in a phonebook entry includes phone numbers, bps rates, user authentication information, and other connection information.

A RAS client uses the parameters of the RasDial function to specify a phonebook file and an entry in that file. The lpszPhonebookPath parameter can specify the name of a phonebook file, or it can be NULL to indicate that the default phonebook file should be used. The lpRasDialParams parameter points to a RASDIALPARAMS structure that specifies the name of the phonebook entry to use.

To display a list of phonebook entries from which the user can select a connection, a RAS client can call the RasEnumEntries function to enumerate the entries in a phonebook file.

To make a connection without using a phonebook entry, the RasDial call can specify an empty string for the szEntryName member of the RASDIALPARAMS structure. The RASDIALPARAMS.szPhoneNumber member must contain the number to call. In this case, the Remote Access Connection Manager uses the first available modem port and default values for all other settings.


User Authentication Information

The Remote Access Connection Manager service on the client computer sends a user name and password to the RAS server on the remote computer. Before it will establish a connection, the remote server uses this information to authenticate the user. By default, the Remote Access Connection Manager sends the user name and password of the currently logged-on user. The RAS client can use the RASDIALPARAMS structure specified in the RasDial call to specify a different user name and password.

If the remote server cannot authenticate the user with the specified information, it can allow the connection operation to enter a paused state to enable the RAS client to collect different authentication data from the user.


Other Connection Information

The members of the RASDIALPARAMS structure can also specify the following connection information:

  • A phone number to override the number in the phonebook entry.
  • A callback phone number that the remote server can call back to establish the connection.
  • The name of the remote network domain on which the authentication is to occur.

For the callback number and the domain, the RASDIALPARAMS members can either indicate that RAS should use the information in the phonebook entry, or it can provide information that overrides the phonebook data.

A RAS client can use the lpRasDialExtensions parameter of the RasDial function to control whether RAS uses a phone number prefix or suffix specified in a phonebook entry.


Connection States

During the process of connecting to a remote server, the Remote Access Connection Manager and the RAS server on the remote computer perform several steps to establish the connection. Each of these steps is identified by a connection state. The RASCONNSTATE enumeration is a set of values that correspond to these connection states. The connection states can be divided into the following three groups:

Running states | The running states are the parts of the connection operation that RAS handles automatically, such as connecting to the necessary devices, authenticating the user, and waiting for a callback from the remote server. Unless an error occurs, the RAS client need take no action other than to pass the notification on to the user.
Paused states | The paused states occur when the remote server pauses the connection operation to get additional input from the user. During a paused state, the user can type a callback number, a different user name and password if the user authentication fails, or a new password if the old one has expired.
Terminal states | The terminal states occur when the connection has been successfully established, the connection operation has failed, or the connection has been broken by a RasHangUp call.

There are several mechanisms that a RAS client can use to determine the current state of a connection operation. When a RAS client executes the RasDial function asynchronously, the Remote Access Connection Manager sends progress notifications to the client's notification handler whenever the connection state changes. In addition, the client can use the RasGetConnectStatus function to get the current state of any RAS connection operation.


Notification Handlers

An asynchronous RasDial call must specify a notification handler. During an asynchronous connection operation, the Remote Access Connection Manager uses the notification handler to inform the RAS client whenever the connection state changes or an error occurs.

The actions performed by a notification handler can be divided into the following categories:

  • Handling errors.
  • Providing feedback to the user as the connection operation proceeds through the various connection states. See Informational Notifications.
  • Handling paused states.
  • Signaling the RAS client application when the connection operation has been completed. See Completion Notifications.

There are three types of notification handlers, each of which receives the same basic information: the current connection state and an error code that is nonzero only if an error has occurred.

RasDialFunc | A callback function prototype that receives only the current connection state and error code information.
RasDialFunc1 | A callback function prototype that receives the HRASCONN connection handle and extended error information in addition to the basic information. The connection handle parameter makes RasDialFunc1 useful for client applications that support multiple simultaneous connection operations. This allows the client to specify the same callback function for all operations, and enables the callback function to determine which connection is changing states.
Window handle | A window handle to which RAS sends WM_RASDIALEVENT messages containing the current connection state and error code information. Use this method if your source code must be compatible with 16-bit Windows, because 16-bit Windows does not support either of the callback functions.

The Remote Access Connection Manager suspends the connection operation until the notification handler returns. For this reason, the handler should return as soon as possible unless an error has occurred.

The RasDial function should not be called from within a notification handler. The other remote access functions (RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp) can be called from within a handler.


Handling RAS Errors

When an error occurs, the Remote Access Connection Manager invokes the client's notification handler. The notification indicates the connection state when the error occurred, and a code that identifies the error. In these cases, the notification handler should call RasHangUp to end the RAS connection.

The RAS client can use the RasGetErrorString function to get a display string describing the error.


Informational Notifications

For the connection states known as running states, no action is required of the notification handler unless an error occurs. Running states occur during the parts of the connection operation that RAS handles automatically, such as connecting to the necessary devices, authenticating the user, and waiting for a callback from the remote server. The notification is simply a progress report to the client.

The client can choose to pass these informational notifications on to the user. In some running states, the client may want to display additional information. For example, a notification handler that receives a RASCS_ConnectDevice notification can call the RasGetConnectStatus function to get the name and type of the device being connected to. Another example is when the client receives a RASCS_Projected notification. This occurs when the RAS projection phase of the connection operation has been completed. The client can call the RasGetProjectionInfo function to get additional information about the projection. The client can use this information to notify the user as to which network protocols can be used by this connection.

You should avoid writing code that depends on the order or occurrence of particular informational states, because this may vary between platforms.


Completion Notifications

The Remote Access Connection Manager continues progress notifications until the connection operation has been completed. This occurs in the following situations:

  • The connection is established. The handler receives a RASCS_Connected notification. The RAS client application can exit without breaking the connection.
  • An error occurs. The handler receives a notification indicating the error and the connection state when the error occurred.
  • The connection operation is interrupted by a RasHangUp call.


Paused States

During a connection operation, there can be times when the remote server cannot proceed without additional information from the local user. Beginning with Microsoft® Windows NT® version 3.5, the RasDial function supports paused states. A paused state allows the Remote Access Connection Manager to suspend a connection operation so the RAS client application can collect information from the user.

Paused states are useful in the following situations:

  • When the user needs to provide a callback number.
  • When the user authentication fails, the user can type in a different user name and password.
  • When the user's password has expired, the user can provide a new password.

By default, paused state support is disabled. RAS clients that want to support paused states must set the RDEOPTS_PausedStates flag in the RASDIALEXTENSIONS structure passed as a parameter to RasDial.

When a paused state occurs, the Remote Access Connection Manager invokes the client's notification handler. If paused state support is disabled, the notification message indicates an error, and the connection operation fails. If it is enabled, the Connection Manager pauses the connection operation to wait for the RAS client's response. The RAS client can resume the connection operation by a second RasDial call, or terminate it by calling the RasHangUp function.

After getting the user's input, the RAS client restarts the connection operation by calling RasDial again. This second RasDial call must specify the following information:

  • The connection handle that was returned by the original RasDial call.
  • The same notification handler as the original RasDial call.
  • The user's input in the appropriate members of the RASDIALPARAMS structure. Other members of the RASDIALPARAMS structure should have the same information as specified in the original RasDial call.

The second RasDial call cannot be made from within the notification handler.


Callback Connections

RAS supports connections in which the remote server hangs up and then calls back to the client to establish the connection.

For each user that can connect to a RAS server, the server stores a callback attribute that controls how the connection is made. The default attribute is No Callback, which means that the user can connect to the RAS server without a callback. Alternatively, the administrator of the RAS server can assign to a user either the Preset or Set-By-Caller callback attribute.

For a user assigned the Preset restriction, the administrator specifies a phone number that the RAS server must call back to establish a connection. The user cannot specify a different number, and the connection cannot be made without a callback.

A Preset callback operation is handled automatically by the Remote Access Connection Manager and the remote server. The RAS client application does not need to do anything other than provide feedback to the user when the notification handler is called during the various states of the callback operation.

A user assigned the Set By Caller privilege can choose to connect either with or without a callback. The RasDial call uses the szCallBackNumber member of the RASDIALPARAMS structure to indicate the choice.

The szCallBackNumber member can simply specify the callback number; or, to establish the connection without a callback, szCallBackNumber can point to an empty string, "". In either of these cases, the Remote Access Connection Manager handles the connection operation automatically. As with a Preset callback operation, the RAS client does not need to perform any action other than to provide feedback to the user.

If the RasDial call enables paused states, szCallBackNumber can point to an asterisk string, "*", to indicate that the connection operation should enter a paused state to allow the user to type in the callback number. In this case, the connection operation for a Set By Caller user enters a paused state after the remote server has authenticated the user. During the paused state, the RAS client gets the callback number input from the user. The client then resumes the connection operation by making a second RasDial call in which szCallBackNumber specifies the number supplied by the user.

Note If paused states are not enabled there is a different meaning when szCallBackNumber points to an asterisk string, "*". In this case, the asterisk indicates that the callback number is stored in the phonebook file specified by the RasDial call.


Disconnecting

When a RAS client application starts a connection operation, the RasDial call receives an HRASCONN connection handle to identify the connection. If the returned handle is not NULL, the client must eventually call the RasHangUp function to end the connection. If an error occurs during the connection operation, the client must call RasHangUp even though the connection was never established.

The application that calls RasHangUp should not exit immediately, because the Remote Access Connection Manager needs time to properly terminate the connection. Instead, the application should wait until the RasGetConnectStatus function returns ERROR_INVALID_HANDLE, indicating that the connection has been deleted.

A RAS client application might need to end a connection even though it does not have the handle returned by RasDial. For example, the application that called RasDial might have exited once the connection was successfully established. In this case, the disconnecting application can use the RasEnumConnections function to get all the current connections. For each connection, RasEnumConnections returns a RASCONN structure containing the HRASCONN connection handle and the phonebook entry name or phone number specified when the connection operation was started. This information can be used to display a list of connections from which the user can select the connection to end.


RAS Phone Books

Phone books provide a standard way to collect and specify the information that the Remote Access Connection Manager needs to establish a remote connection. Phone books associate entry names with information such as phone numbers, COM ports, and modem settings. Each phone-book entry contains the information needed to establish a RAS connection.

Windows NT: Phone books are stored in phone-book files, which are text files that contain the entry names and associated information. RAS creates a phone-book file called RASPHONE.PBK. The user can use the main Dial-Up Networking dialog box to create personal phone-book files. The Win32 API does not currently provide support for creating a phone-book file. Some RAS functions, such as the RasDial function, have a parameter that specifies a phone-book file. If the caller does not specify a phone-book file, the function uses the default phone-book file, which is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows NT version 4.0 provides the RasPhonebookDlg and RasEntryDlg functions that display the built-in RAS user interface that enable users to work with phone books and phone-book entries.

Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file. Windows 95 does not support personal phone-book files. Windows 95 does not support the functions that display the built-in RAS dialog boxes.


Phone-book Entries

Phone-book entries contain the information necessary to establish a RAS connection. A user or administrator can use the Dial-Up Networking dialog box to create, edit, and dial phone-book entries.

Windows 95: Windows 95 supports a limited set of the Win32 functions for working with phone-book entries. You can use the RasCreatePhonebookEntry and RasEditPhonebookEntry functions to create or edit a phone-book entry. These functions display a dialog box in which the user can specify information about the phone-book entry. You can use the RasGetEntryDialParams and RasSetEntryDialParams functions to set or retrieve the connection parameters for a phone-book entry. The RasEnumEntries function retrieves an array of RASENTRYNAME structures that contain the phone-book entry names.

Windows NT version 4.0 supports the functions described for Windows 95, as well as a number of additional functions that an application can use to work with phone books and phone-book entries.

The RasEntryDlg function displays a property sheet that enables the user to create, edit, or copy phone-book entries. The RasCreatePhonebookEntry and RasEditPhonebookEntry functions call the RasEntryDlg function. You can use the RasRenameEntry function to rename a phone-book entry, or the RasDeleteEntry to delete an entry. The RasValidateEntryName determines whether a specified string has the correct format to be used as an entry name.

You can use the RasGetEntryProperties and RasSetEntryProperties to get and set additional information about a phone-book entry. These functions use a RASENTRY structure.

The RasGetCredentials and RasSetCredentials functions get and set the user credentials associated with a specified RAS phone-book entry. These functions use a RASCREDENTIALS structure.

The RasGetCountryInfo function retrieves country-specific dialing information from the Windows Telephony list of countries. RasGetCountryInfo uses the RASCTRYINFO structure.


Subentries and Multilink Connections

Windows NT version 4.0 provides support for phone-book subentries, which enable multilink connections. A multilink connection combines the bandwidth of multiple connections to provide a single connection with higher bandwidth.

A RAS phone-book entry can have zero or more subentries. The RasGetEntryProperties function retrieves a RASENTRY structure that includes information about the subentries of a phone-book entry. The dwSubEntries member of the RASENTRY structure indicates the number of subentries. Phone-book entries initially have no subentries. To add subentries to a phone-book entry, use the RasSetSubEntryProperties function.

The properties for each subentry include a phone number and the name and type of the TAPI device to use when dialing the subentry. In addition, a subentry can include a list of alternate phone numbers to dial if RAS cannot make a connection using the primary number. The RasSetSubEntryProperties and RasGetSubEntryProperties functions use the RASSUBENTRY structure to set and retrieve the properties of a specified phone-book subentry. Subentries are identified by a one-based index.

You can call the RasSetEntryProperties function to configure a multilink RAS entry to connect all subentries when it is first dialed. Alternatively, you can configure an entry to provide variable bandwidth. In this case, RAS connects a single subentry initially, and then connects or disconnects additional subentries as needed. For a variable-bandwidth multilink connection, you can use the RASDIALPARAMS structure to specify the initial subentry to connect when you call the RasDial function. When using the RasDialDlg function to connect a multilink entry, you can use the RASDIALDLG structure to specify the initial subentry to connect.

For a variable-bandwidth multilink connection, use the RASENTRY structure with the RasSetEntryProperties function to specify the parameters for connecting and disconnecting the individual subentries. RAS connects an additional subentry when the bandwidth being used exceeds a specified percentage of the available bandwidth for a specified interval.

If you call the RasDial function to establish a multilink connection, you can specify a RasDialFunc2 callback function to receive notifications about the connection. RasDialFunc2 is similar to the RasDialFunc1 callback function, except that it provides additional information for a multilink connection, such as the index of the subentry that caused the notification. RAS calls your RasDialFunc2 function when it connects or disconnects a subentry.

You can use an HRASCONN connection handle to hang up or retrieve information about a multilink connection. You can get a connection handle for each of the subentry connections that make up the multilink, as well as for the combined multilink connection. When you call the RasDial function to establish a multilink connection, RasDial returns a handle to the combined multilink connection. Similarly, RasEnumConnections returns the combined multilink handle when you enumerate connections. To get a handle to one of the subentry connections in a multilink connection, call the RasGetSubEntryHandle function.

You can use the combined multilink connection handle and the subentry connection handles in the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfo functions. Calling RasHangUp with a combined multilink handle terminates the entire connection; calling it with a subentry handle hangs up only that subentry connection. Similarly, RasGetConnectStatus returns information for the combined or individual connection, depending on the handle specified. The projection information returned by RasGetProjectionInfo for a multilink entry is the same for each of the subentry connection handles as it is for the main connection handle.


RAS AutoDial

Windows NT version 4.0 supports a feature known as AutoDial. Windows 95 and Windows NT version 3.51 and earlier do not support the AutoDial feature.

When an attempt to connect to a network address fails because the host cannot be reached, the AutoDial feature can automatically start a dial-up connection operation. To do this, AutoDial searches its database of network addresses to find a phone-book entry that it can use to establish the connection.


AutoDial Mapping Database

The AutoDial mapping database maps network addresses to RAS phone-book entries. The database can include IP addresses (for example, "127.95.1.4"), Internet host names (for example, "www.microsoft.com"), or NetBIOS names (for example, "products1"). Associated with each address in the AutoDial database is a set of one or more RASAUTODIALENTRY entries. Each of these entries specifies a phone-book entry that RAS can dial to connect to the address from a particular Telephony Application Programming Interface (TAPI) dialing location. For more information about TAPI dialing locations, see the TAPI documentation.

AutoDial automatically creates entries in the AutoDial mapping database in two situations:

  • When an attempt to connect to a network address fails

    If there is no entry for the address in the mapping database, and the computer is not connected to a network (either directly or through RAS), AutoDial prompts the user to specify the information necessary to establish a dial-up connection. If the user provides the information and the dial-up connection operation is successful, AutoDial stores the information in the mapping database.

  • When the computer is connected to a network through RAS

    Whenever the user connects to a network address, AutoDial creates an entry in the database. The entry maps the network address to the phonebook entry that was used to establish the RAS connection.

You can use the RasSetAutodialAddress function to add an address to the AutoDial mapping database, delete an address from the database, or change the AutoDial entries associated with an existing address in the database. You can use the RasGetAutodialAddress function to retrieve the AutoDial entries associated with a specified network address in the AutoDial mapping database. The RasEnumAutodialAddresses function returns a list of all addresses in the AutoDial mapping database.


AutoDial Connection Operations

When an attempt to connect to a network address fails because the host cannot be reached, the system searches the AutoDial mapping database for the address. If the address is in the database, the system initiates an AutoDial operation for the RASAUTODIALENTRY, if any, that corresponds to the local TAPI dialing location.

The Win32 API provides functions that enable you to set and query AutoDial parameters that control AutoDial connections. You can call the RasSetAutodialEnable function to enable or disable the AutoDial feature for a specified TAPI dialing location. The RasGetAutodialEnable function indicates whether the AutoDial feature is enabled for a specified TAPI dialing location. For more information about TAPI dialing locations, see the TAPI documentation. You can call the RasSetAutodialParam function to set other AutoDial connection parameters. For example, you can disable AutoDial connections for the current logon session. Call the RasGetAutodialParam function to determine the current value of the AutoDial connection parameters.

The system provides a default user interface for AutoDial dialing operations. However, you can create an AutoDial dynamic-link library (DLL) to provide a custom user interface for AutoDial dialing operations involving specified phone-book entries. Your AutoDial DLL must export both an ANSI and a Unicode version of a RASADFunc AutoDial handler.

To enable your custom AutoDial handler for a phone-book entry, call the RasSetEntryProperties function to set the properties for that entry. The szAutodialDll and szAutodialFunc members of the RASENTRY structure passed to RasSetEntryProperties specify the name of your AutoDial DLL and the name of your RASADFunc function, excluding the "A" or "W" suffix.

When the system starts an AutoDial operation for a phone-book entry with a custom AutoDial handler, it calls the specified RASADFunc. The RASADFunc function receives a pointer to a RASADPARAMS structure that indicates the location and parent window for the window of your user interface. Your RASADFunc can start a thread to perform the custom dialing operation. The RASADFunc function returns TRUE to indicate that it took over the dialing, or FALSE to allow the system to perform the dialing. Your custom dialing operation must use the RasDial function to do the actual dialing. When the dialing operation has been completed, the custom dialing operation indicates success or failure by setting the variable pointed to by the lpdwRetCode parameter passed to RASADFunc.


RAS Configuration and Connection Information

Applications running on Windows NT and Windows 95 can use the RasEnumConnections function to get information about the existing connections on the local computer. The information for each connection includes a connection handle and the name of the phone-book entry used to establish the connection. You can use the connection handle in a call to the RasGetConnectStatus function get the current status of the connection.

Windows NT version 4.0 provides two new functions for retrieving RAS information. Windows 95 does not support these functions.

The RasEnumDevices function returns the name and type of the RAS-capable devices that are configured on the local computer.

You can use the RasConnectionNotification function to specify an event object that the system signals when a RAS connection is created or terminated.


RAS Server Administration

Windows NT version 4.0 provides a set of functions for administering user permissions and ports on Windows NT RAS servers. Windows 95 does not support these functions. Using these functions, you can develop a RAS server administration application to perform the following tasks:

  • Enumerate those users who have a specified set of RAS permissions
  • Assign or revoke RAS permissions for a specified user
  • Enumerate the configured ports on a RAS server
  • Get information and statistics about a specified port on a RAS server
  • Reset the statistics counters for a specified port
  • Disconnect a specified port

You can also install a RAS server administration DLL for auditing user connections and assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS server calls whenever a user tries to connect or disconnect.


RAS User Account Administration

A Windows NT RAS server uses a user account database that contains information about a set of user accounts. The information includes a user's RAS privileges, which are a set of bit flags that determine how the RAS server responds when the user calls to connect. The RAS server administration functions enable you to locate the user account database, and to get and set the RAS privileges for user accounts.

A Windows NT RAS server can be part of a Windows NT domain, or it can be a stand-alone Windows NT Server or Workstation that is not part of a domain. For a server that is part of a domain, the user account database is stored on the Windows NT server that is the primary domain controller (PDC). A stand-alone server stores its own local user account database. To get the name of the server that stores the user account database used by a specified RAS server, you can call the RasAdminGetUserAccountServer function. You can then use the name of the user account server in a call to the NetQueryDisplayInformation function to enumerate the users in a user account database. You can also use the server name in calls to the RasAdminUserGetInfo and RasAdminUserSetInfo functions to get and set the RAS privileges for a specified user account.

The RasAdminUserGetInfo and RasAdminUserSetInfo functions use the RAS_USER_0 structure to specify a user's RAS privileges and call-back phone number. The RAS privileges indicate the following information:

  • Whether the user can make a remote connection to the server or the domain to which the server belongs.
  • Whether the user can establish a connection through a call-back, in which the RAS server hangs up and then calls back to the user to establish the connection.

Each user account specifies one of the following flags to indicate the user's call-back privilege.

Value | Meaning
RASPRIV_NoCallback | The RAS server will not call back the user to establish a connection.
RASPRIV_AdminSetCallback | When the user calls, the RAS server hangs up and calls a preset call-back phone number stored in the user account database. The szPhoneNumber member of the RAS_USER_0 structure contains the user's call-back phone number.
RASPRIV_CallerSetCallback | When the user calls, the RAS server provides the option of specifying a call-back phone number. The user can also choose to connect immediately without a call back. The szPhoneNumber member contains a default number that the user can override.


RAS Server and Port Administration

The RAS server administration functions enable you to get information about a specified RAS server and its ports. These functions also enable you to terminate a connection on a specified RAS server port.

The RasAdminServerGetInfo function returns a RAS_SERVER_0 structure that contains information about the configuration of a RAS server. The returned information includes the number of ports currently available for connection, the number of ports currently in use, and the server version number.

The RasAdminPortEnum function retrieves an array of RAS_PORT_0 structures that contains information for each of the ports configured on a RAS server. The information for each port includes:

  • The name of the port
  • Information about the device attached to the port
  • Whether the RAS server associated with the port is a Windows NT Server
  • Whether the port is currently in use, and if it is, information about the connection

You can call the RasAdminPortGetInfo function to get additional information about a specified port on a RAS server. This function returns a RAS_PORT_1 structure that contains a RAS_PORT_0 structure and additional information about the current state of the port. The RasAdminPortGetInfo function also returns an array of RAS_PARAMETERS structures that describe the values of any media-specific keys associated with the port. A RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT enumeration to indicate the format of the value for each media-specific key.

The RasAdminPortGetInfo function also returns a RAS_PORT_STATISTICS structure that contains various statistic counters for the current connection, if any, on the port. For a port that is part of a multilink connection, RasAdminPortGetInfo returns statistics for the individual port and cumulative statistics for all ports involved in the connection. You can use the RasAdminPortClearStatistics function to reset the statistic counters for the port. The RasAdminPortDisconnect function disconnects a port that is in use.

Use the RasAdminFreeBuffer function to free memory allocated by the RasAdminPortEnum and RasAdminPortGetInfo functions. Use the RasAdminGetErrorString function to get a string that describes a RAS error code returned by one of the RAS server administration (RasAdmin) functions.


RAS Administration DLL

Windows NT version 4.0 enables you to install a RAS administration DLL on a Windows NT RAS server. The DLL exports functions that the RAS server calls whenever a user tries to connect or disconnect. You can use the DLL to perform the following administrative functions:

  • Decide whether to allow a user to connect to the server. This can provide a security check in addition to the standard RAS user authentication.
  • Record the time that each user connects to and disconnects from the server. This can be useful for billing or auditing purposes.
  • Assign an IP address to each user. This can be useful for security purposes to map a user's connection to a specific computer.

The RasAdminAcceptNewConnection and RasAdminConnectionHangupNotification functions enable the DLL to audit user connections to the server. A Windows NT RAS server calls the DLL's RasAdminAcceptNewConnection function whenever a user tries to connect. The function can prevent the user from connecting. You can also use the function to generate an entry in a log for billing or auditing. When the user disconnects, the RAS server calls the DLL's RasAdminConnectionHangupNotification function, which can log the time at which the user disconnected.

After the RAS server has authenticated a caller, it calls the DLL's RasAdminGetIpAddressForUser function to get an IP address for the dialed-in remote client. The DLL can use this function to provide an alternate scheme for mapping an IP address to a dial-in user. By default, a RAS server connects a remote user to an IP address selected from a static pool of IP addresses, or one selected by a Dynamic Host Configuration Protocol (DHCP) server. The RasAdminGetIpAddressForUser function allows the DLL to override the default IP address and specify a particular IP address for each user. The RasAdminGetIpAddressForUser function can set a flag that causes RAS to call the DLL's RasAdminReleaseIPAddress function when the user disconnects. The DLL can use RasAdminReleaseIPAddress to update its user-to-IP-address map.

Note that RAS executes the functions for assigning IP addresses in one process, and executes the functions for connection and disconnection notifications in another process. Consequently, the DLL should not depend on shared data between the two sets of functions.

The RAS server logs an error in the system event log if an error occurs when it tries to load a RAS administration DLL or when it calls one of the DLL's functions. This can happen, for example, if the DLL specified the wrong name for an exported function, or if it did not include the function name in the .DEF file. The entry in the event log indicates the reason for the failure.


RAS Administration DLL Registry Setup

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value Name | Value Data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS Administration DLL from a fictional company named Netwerks Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
    DisplayName  :  REG_SZ  :  Netwerks RAS Admin DLL
    DLLPath      :  REG_SZ  :  C:\nt\system32\ntwkadm.dll

The setup program for a RAS Administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.


RAS Security Host Support

Windows NT version 4.0 provides a way for a third-party RAS security DLL to enhance the built-in RAS security features. Windows 95 does not provide this support.

The Windows NT RAS server provides security mechanisms for validating the network access of remote users. When a RAS server receives a call, it validates the user's credentials against the local or domain account database. RAS also supports call-back security, in which the RAS server hangs up and then calls back to the remote user to establish the connection. For networks in which this level of security is not enough, you can install a third-party RAS security DLL. The security DLL can then authenticate a remote user by reading security information from a database other than the standard Windows NT user account database.

When the RAS server receives a call, it invokes the security DLL to authenticate the remote user. The RAS security host support provides a mechanism for the security DLL to communicate with the remote user through a terminal window on the remote computer. In a typical scenario, the security DLL asks for the logon name of the remote user. The DLL then uses its private security database to formulate a challenge to send to the remote terminal. For example, the challenge could be a code that the user must provide as input to a cardkey reader. The cardkey reader then displays a response that the remote user types in the terminal window. The security DLL then validates the response against the user's information in the private security database.

If the security DLL authenticates the remote user, the RAS server performs its own authentication. This ensures that RAS security always authenticates a remote user, even if a security DLL is installed that grants access to all users.

Note Windows NT currently provides RAS security host support only for asynchronous connections; other media, such as ISDN, are not supported.


Registering a RAS Security DLL

The setup program for a RAS security DLL must register the DLL with the Windows NT RAS server. Only one RAS security DLL can be registered; Windows NT does not support multiple security DLLs. To register a RAS security DLL, set the DLLPath value under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\SecurityHost

Value Name | Value Data
DLLPath | A REG_SZ string that contains the path of the DLL. This string should specify the full path unless the DLL is in a directory listed in the system path.

The setup program for a RAS security DLL must also provide remove/uninstall functionality. If a user removes the DLL, the setup program must delete the DLLPath value from the registry. The RAS service will not start if the DLLPath value specifies a DLL that cannot be found.

A RAS security DLL must export the RasSecurityDialogBegin and RasSecurityDialogEnd functions.


RAS Server Security Authentication

When a Windows NT RAS server receives a call, it invokes the RasSecurityDialogBegin function of the registered RAS security DLL, if there is one. This call notifies the security DLL to begin its authentication of the remote user. The RAS server calls RasSecurityDialogBegin before performing its PPP or RAS authentication.

The RasSecurityDialogBegin call passes the following information to the security DLL:

  • A port handle to identify the connection
  • Pointers to buffers to use when communicating with the remote user
  • A pointer to a RasSecurityDialogComplete function to call when the authentication has been completed

The port handle and buffer pointers are valid until the security DLL calls RasSecurityDialogComplete to terminate the authentication transaction.

The RasSecurityDialogComplete notifies the RAS server of the results of the security DLL's authentication of the remote user. If the security DLL reports success, the RAS server proceeds with its PPP and RAS authentication of the remote user. If the security DLL reports that the remote user failed the authentication, or that an error occurred, the RAS server hangs up and logs the error or failed authentication in the Windows NT event log.


RAS Security DLL Authentication Transaction

The Windows NT RAS server calls the security DLL's RasSecurityDialogBegin function to begin an authentication of a remote user. The RAS server is blocked and cannot accept any other calls until RasSecurityDialogBegin returns. For this reason, RasSecurityDialogBegin should copy the input parameters, create a thread to perform the authentication, and return as quickly as possible.

The thread created by the security DLL uses the RasSecurityDialogSend and RasSecurityDialogReceive functions to communicate with the remote computer. These functions are not available for static import from any library. Instead, the security DLL must use the LoadLibrary and GetProcAddress functions to dynamically link to these functions in RASMAN.DLL.

During an authentication transaction, the RAS connection manager on the remote computer displays a terminal window. The thread of the security DLL calls RasSecurityDialogSend to send a message to display in the terminal window. The thread then calls RasSecurityDialogReceive to receive the input that the remote user types in the terminal window. The thread can make any number of RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive call. After each call to RasSecurityDialogReceive, the thread must call one of the wait functions, such as WaitForSingleObject, to wait for the asynchronous send and receive operations to be completed. The RAS server signals an event object when the receive operation has been completed or when an optional time-out interval has elapsed.

When the thread has finished authenticating the remote user, it calls the RasSecurityDialogComplete function. This call passes a SECURITY_MESSAGE structure containing the results of the authentication transaction to the RAS server. The RAS server then performs a cleanup sequence that includes a call to the DLL's RasSecurityDialogEnd function. This gives the security DLL an opportunity to perform any necessary cleanup.

The security DLL can call the RasSecurityDialogGetInfo function to retrieve information about the port associated with an authentication transaction. RasSecurityDialogGetInfo fills in a RAS_SECURITY_INFO structure that indicates the state of the last RasSecurityDialogReceive call for the port


Using Remote Access Service

The following topic explains how to use Remote Access Service features in an application.

  • Linking to the remote access DLL


Linking to the Remote Access DLL

If an application links statically to the RASAPI32 DLL, the application will fail to load if Remote Access Service is not installed. A RAS application can load when RAS is not installed by using LoadLibrary to load the DLL, and GetProcAddress to obtain pointers to the RAS functions.

The Win32 RAS functions are in RASAPI32.DLL. The import library for these functions is RASAPI32.LIB. To use the RAS functions, your programs must include the following files:

File | Description
RAS.H | Contains the RAS function prototypes, constants, and structure definitions.
RASERROR.H | Contains the RAS error codes.


Remote Access Service and RAS Server Administration Reference

The following functions, structures, messages, and enumeration types are associated with remote access service.

  • Remote Access Service Functions
  • Remote Access Service Structures
  • Remote Access Service Messages
  • Remote Access Service Enumeration Types
  • RAS Server Administration Functions
  • RAS Server Administration Structures
  • RAS Server Administration Union
  • RAS Server Administration Enumeration Types


Remote Access Service Functions

Use the following functions to implement Remote Access Service functionality.

ORASADFunc
RASADFunc
RasConnectionNotification
RasCreatePhonebookEntry
RasDeleteEntry
RasDial
RasDialFunc
RasDialFunc1
RasDialFunc2
RasDialDlg
RasEditPhonebookEntry
RasEntryDlg
RasEnumAutodialAddresses
RasEnumConnections
RasEnumDevices
RasEnumEntries
RasGetAutodialAddress
RasGetAutodialEnable
RasGetAutodialParam
RasGetConnectStatus
RasGetCountryInfo
RasGetCredentials
RasGetEntryDialParams
RasGetEntryProperties
RasGetErrorString
RasGetProjectionInfo
RasGetSubEntryHandle
RasGetSubEntryProperties
RasHangUp
RasMonitorDlg
RasPBDlgFunc
RasPhonebookDlg
RasRenameEntry
RasSetAutodialAddress
RasSetAutodialEnable
RasSetAutodialParam
RasSetCredentials
RasSetEntryDialParams
RasSetEntryProperties
RasSetSubEntryProperties
RasValidateEntryName


RAS Server Administration Functions

For Windows NT version 4.0, use the following functions to implement RAS Server Administration functionality. Windows 95 does not provide RAS server support.

RasAdminAcceptNewConnection
RasAdminConnectionHangupNotification
RasAdminFreeBuffer
RasAdminGetErrorString
RasAdminGetIpAddressForUser
RasAdminGetUserAccountServer
RasAdminPortClearStatistics
RasAdminPortDisconnect
RasAdminPortEnum
RasAdminPortGetInfo
RasAdminReleaseIpAddress
RasAdminServerGetInfo
RasAdminUserGetInfo
RasAdminUserSetInfo
RasSecurityDialogBegin
RasSecurityDialogComplete
RasSecurityDialogEnd
RasSecurityDialogGetInfo
RasSecurityDialogReceive
RasSecurityDialogSend


ORASADFunc

The ORASADFunc function is an application-defined callback function that you can use to provide a customized user interface for autodialing.

This prototype is provided for compatibility with earlier versions of Windows. New applications should use the RASADFunc callback function. Support for this prototype may be removed in future versions of RAS.

BOOL WINAPI ORASADFunc(
  HWND hwndOwner,  // handle of an owner window
  LPSTR lpszEntry, // pointer to a phone-book entry
  DWORD dwFlags,   // reserved; must be zero
  LPDWORD lpdwRetCode
                   // receives the results of a dialing operation
);

Parameters

hwndOwner
Handle of the owner window.
lpszEntry
Pointer to a null-terminated string that specifies the phone-book entry to use.
dwFlags
Reserved; must be zero.
lpdwRetCode
Pointer to a variable that the callback function fills in with the results of the dialing operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If the dialing operation fails, set it to a nonzero value.

Return Values

If the callback function performs the dialing operation, return TRUE. Use the lpdwRetCode parameter to indicate the results of the dialing operation.

If the callback function does not perform the dialing operation, return FALSE. In this case, the system uses the default user interface for dialing.

Remarks

If your ORASADFunc function performs the dialing operation, it presents its own user interface for dialing and calls the RasDial function to do the actual dialing. Your ORASADFunc then returns TRUE to indicate that it took over the dialing. When the dialing operation has been completed, set the variable pointed to by lpdwRetCode to indicate success or failure.

To enable an ORASADFunc handler for a phone-book entry, use the RASENTRY structure in a call to the RasSetEntryProperties function. The szAutodialDll member specifies the name of the DLL that contains the handler, and the szAutodialFunc member specifies the exported name of the handler.

The ORASADFunc function is a placeholder for the library-defined function name. The ORASADFUNC type is a pointer to an ORASADFunc function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: User-defined.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASADFunc, RasDial, RASENTRY, RasSetEntryProperties


RASADFunc

The RASADFunc function is an application-defined callback function that you can use to provide a customized user interface for autodialing.

BOOL WINAPI RASADFunc(
  LPTSTR lpszPhonebook,  // pointer to full path and filename of
                         // phone-book file
  LPTSTR lpszEntry,      // pointer to the entry name to validate
  LPRASADPARAMS lpAutodialParams,
                         // pointer to a RASADPARAMS structure
  LPDWORD lpdwRetCode    // receives results of dialing operation
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that specifies the phone-book entry to use.
lpAutoDialParams
Pointer to a RASADPARAMS structure that indicates how to position the window of your AutoDial user interface. The structure may also specify a parent window for your AutoDial window.
lpdwRetCode
Pointer to a variable in which you must return a value if you perform the dialing operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If the dialing operation fails, set it to a nonzero value.

Return Values

If your application performs the dialing operation, return TRUE. Use the lpdwRetCode parameter to indicate the results of the dialing operation.

If your application does not perform the dialing operation, return FALSE. In this case, the system uses the default user interface for dialing.

Remarks

When the system starts an AutoDial operation for a phone-book entry with a custom AutoDial handler, it calls the specified RASADFunc. Your RASADFunc can start a thread to perform the custom dialing operation. The RASADFunc function returns TRUE to indicate that it took over the dialing, or FALSE to allow the system to perform the dialing.

If your RASADFunc function performs the dialing operation, it presents its own user interface for dialing and calls the RasDial function to do the actual dialing. Your RASADFunc then returns TRUE to indicate that it took over the dialing. When the dialing operation has been completed, set the variable pointed to by the lpdwRetCode parameter to indicate success or failure.

Your AutoDial DLL must provide both a RASADFUNCA (ANSI) and a RASADFUNCW (Unicode) version of the RASADFunc handler. To enable a RASADFunc AutoDial handler for a phone-book entry, use the RASENTRY structure in a call to the RasSetEntryProperties function. The szAutodialDll member specifies the name of the DLL that contains the handler, and the szAutodialFunc member specifies the exported name of the handler. The szAutodialFunc member should not include the "A" or "W" suffix.

RASADFunc is a placeholder for the library-defined function name. The RASADFUNC type is a pointer to a RASADFunc function.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: User-defined.
Unicode: Defined as Unicode and ANSI prototypes.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDial, RASENTRY, RasSetEntryProperties


RasAdminAcceptNewConnection

The RasAdminAcceptNewConnection function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function when a user tries to establish a remote connection to a RAS server. The function decides whether the user is allowed to connect.

The RAS server calls RasAdminAcceptNewConnection once for each port in a multilink connection.

BOOL RasAdminAcceptNewConnection(
  RAS_PORT_1 *pRasPort1,  // pointer to information about the
                          // connection
  RAS_PORT_STATISTICS *pRasStats,
                          // pointer to statistics about the port
  RAS_PARAMETERS *pRasParams  // pointer to an array of
                              // media-specific parameters and values
);

Parameters

pRasPort1
Pointer to a RAS_PORT_1 structure that contains RAS data about the pending connection. This structure contains the relevant connection information that you need to make a decision about the connection.
pRasStats
Pointer to a RAS_PORT_STATISTICS structure that contains statistics about the port.
pRasParams
Pointer to an array of RAS_PARAMETERS structures. Each structure contains the name of a media-specific key, such as MAXCONNECTBPS, and its associated value.

Return Values

If the function returns TRUE, RAS accepts the new connection.

If the function returns FALSE, RAS does not accept the new connection. There is no exteded error information for this function; do not call GetLastError.

Remarks

The RasAdminAcceptNewConnection function gives more control to a RAS server administration DLL to determine whether a specified remote user should be allowed to connect to a server.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value Name | Value Data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS Administration DLL from a fictional company named Netwerks Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
    DisplayName  :  REG_SZ  :  Netwerks RAS Admin DLL
    DLLPath      :  REG_SZ  :  C:\nt\system32\ntwkadm.dll

The setup program for a RAS Administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminConnectionHangupNotification

The RasAdminConnectionHangupNotification function is an application-defined function that is exported by a third-party RAS server administration DLL. When RAS disconnects an existing connection, it calls this function to notify your DLL.

The RAS server calls RasAdminConnectionHangupNotification once for each port in a multilink connection.

VOID RasAdminConnectionHangupNotification(
  RAS_PORT_1 *pRasPort1,  // pointer to information about the
                          // connection
  RAS_PORT_STATISTICS *pRasStats,
                          // pointer to statistics about the port
  RAS_PARAMETERS *pRasParams  // pointer to an array of
                              // media-specific parameters and values
);

Parameters

pRasPort1
Pointer to a RAS_PORT_1 structure that contains RAS data about the connection that ended. This structure contains the relevant connection information that you can use to determine how long the port was connected.
pRasStats
Pointer to a RAS_PORT_STATISTICS structure that contains statistics about the port. RAS began accumulating these statistics when the connection was first established.
pRasParams
Pointer to an array of RAS_PARAMETERS structures. Each structure contains the name of a media-specific key, such as MAXCONNECTBPS, and its associated value.

Return Values

The function does not return a value. There are no extended error information for this function; do not call GetLastError.

Remarks

The RAS call to the RasAdminConnectionHangupNotification function is just a notification; no action is required from your DLL. You can use the information provided by this function for accounting purposes.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value Name | Value Data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS Administration DLL from a fictional company named Netwerks Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
    DisplayName  :  REG_SZ  :  Netwerks RAS Admin DLL
    DLLPath      :  REG_SZ  :  C:\nt\system32\ntwkadm.dll

The setup program for a RAS Administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminFreeBuffer

The RasAdminFreeBuffer function frees memory that was allocated by RAS on behalf of the caller.

DWORD RasAdminFreeBuffer(
  PVOID Pointer  // pointer to the buffer to free
);

Parameters

Pointer
Pointer to the buffer to be freed.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | The Pointer parameter is invalid.

There is no extended error information for this function; do not call GetLastError.

Remarks

Use the RasAdminFreeBuffer function to free the buffers allocated by the RasAdminPortEnum and RasAdminPortGetInfo functions.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasAdminPortEnum, RasAdminPortGetInfo


RasAdminGetErrorString

The RasAdminGetErrorString function retrieves a message string that corresponds to a RAS error code returned by one of the RAS server administration (RasAdmin) functions. These message strings are retrieved from the RASMSG.DLL that is installed as part of RAS.

DWORD RasAdminGetErrorString (
  UINT ResourceId,    // error code to get message for
  WCHAR *lpszString,  // pointer to a buffer that receives the error
                      // string
  DWORD InBufSize     // size, in characters, of the buffer
);

Parameters

ResourceId
Specifies an error code returned by one of the RasAdmin functions. This value must be in the range of error codes from RASBASE to RASBASEEND that are defined in RASERROR.H.
lpszString
Pointer to a buffer that receives the error message corresponding to the specified error code.
InBufSize
Specifies the size, in characters, of the lpszString buffer. Error messages are typically 80 characters or less; a buffer size of 512 characters is always adequate.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. This value can be a last error value set by the LoadLibrary, GlobalAlloc, or LoadString functions; or it can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The ResourceId or lpszString parameters are invalid.
ERROR_INSUFFICIENT_BUFFER | The size specified by the InBufSize parameter is too small.

There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdmin functions can return error codes that are not in the range supported by the RasAdminGetErrorString function. For example, the RasAdmin functions can return error codes that are defined in LMERR.H and WINERROR.H. Before calling RasAdminGetErrorString, verify that the error code is in the range RASBASE to RASBASEEND, as defined in RASERROR.H.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, LoadLibrary, GlobalAlloc, LoadString


RasAdminGetIpAddressForUser

The RasAdminGetIpAddressForUser function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function to get an IP address for the dialed-in remote client.

DWORD RasAdminGetIpAddressForUser(
  WCHAR *lpszUserName, // pointer to the name of the remote user
  WCHAR *lpszPortName, // pointer to the name of the port
  IPADDR *pipAddress,  // pointer to the IP address
  BOOL *bNotifyRelease // indicates whether RAS should call
                       // RasAdminReleaseIpAddress
);

Parameters

lpszUserName
Pointer to a null-terminated Unicode string that contains the name of the remote user for whom an IP address is required.
lpszPortName
Pointer to a null-terminated Unicode string that contains the name of the port on which the user specified by lpszUserName is attempting to connect.
pipAddress
Pointer to an IPADDR variable. On input, *pipAddress contains either zero or the IP address that the RAS server proposes to use for the dialed-in remote client. The function can set *pipAddress to a different IP address, or accept the passed-in IP address. If *pipAddress is zero on input, the function must provide an IP address; otherwise, the client will be unable to connect to this server using IP.
bNotifyRelease
Pointer to a BOOL variable. Set this variable to TRUE if you want RAS to call your RasAdminReleaseIpAddress function when the user disconnects from this port; otherwise, set it to FALSE.

Return Values

If pipAddress points to an IP address that the client can use to connect to this RAS server, the function should return NO_ERROR. This can occur if the function accepts the IP address that was passed by the RAS server, or if the function provides a different IP address.

If pipAddress does not point to an IP address, the function should return a nonzero error code. This can occur if no IP address is available, or if the passed in IP address is unacceptable. In this case, the client will be unable to connect to this server using IP. There is no extended error information for this function; do not call GetLastError.

Remarks

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value Name | Value Data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS Administration DLL from a fictional company named Netwerks Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
    DisplayName  :  REG_SZ  :  Netwerks RAS Admin DLL
    DLLPath      :  REG_SZ  :  C:\nt\system32\ntwkadm.dll

The setup program for a RAS Administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasAdminReleaseIpAddress


RasAdminGetUserAccountServer

The RasAdminGetUserAccountServer function retrieves the name of the server that has the user account database. You can use the returned server name in the RasAdminUserGetInfo and RasAdminUserSetInfo functions to get or set information about a specified user.

DWORD RasAdminGetUserAccountServer(
  const WCHAR *lpszDomain,  // pointer to the name of the Windows NT
                            // domain
  const WCHAR *lpszServer,  // pointer to the name of the RAS server
  LPWSTR lpszUserAccountServer  // receives the name of the user
                                // account server
);

Parameters

lpszDomain
Pointer to a null-terminated Unicode string that contains the name of the domain to which the RAS server belongs. This parameter can be NULL if you are running your RAS administration application on a Windows NT Workstation or Server that is not participating in a Windows NT domain. If this parameter is NULL, the lpszServer parameter must be non-NULL.
lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. Specify the name with leading "\\" characters, in the form: \\servername. This parameter can be NULL if the lpszDomain parameter is not NULL.
lpszUserAccountServer
Pointer to a buffer that receives a null-terminated Unicode string containing the name of the primary domain controller (PDC) Windows NT server that has the user account database. The buffer should be big enough to hold the server name (UNCLEN +1). The function prefixes the returned server name with leading "\\" characters, in the form: \\servername. If the server name specified by lpszServer is a stand-alone Windows NT Server or Workstation (that is, the server or workstation does not participate in a Windows NT domain), then the server name itself is returned in the lpszUserAccountServer buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | Both lpszDomain and lpszServer are NULL.

There is no extended error information for this function; do not call GetLastError.

Remarks

The lpszDomain parameter should specify a valid Windows NT domain name. If you are running your RAS administration application on a Windows NT Workstation or Server that is not participating in a Windows NT domain (for example, the workstation or server is in its own work group), then set lpszDomain to NULL. In this case, you must specify your server name in the lpszServer parameter. Be sure to prefix the server name with the "\\" characters. To get the server name, call the GetComputerName function.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, GetComputerName, RasAdminUserGetInfo, RasAdminUserSetInfo


RasAdminPortClearStatistics

The RasAdminPortClearStatistics function resets the counters representing the various statistics reported by the RasAdminPortGetInfo function in the RAS_PORT_STATISTICS structure. The counters are reset to zero and start accumulating from then on.

DWORD RasAdminPortClearStatistics(
  const WCHAR *lpszServer,  // pointer to the server name
  const WCHAR *lpszPort  // pointer to the name of port on the server
);

Parameters

lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
Pointer to a null-terminated Unicode string that contains the name of the port on the server.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_DEV_NOT_EXIST | The specified port is invalid.

There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdminPortClearStatistics function clears the statistics on the server, not locally within the application that makes the call. This means that the statistics are also reset for any other application that is monitoring the specified port.

If the lpszPort port is part of a multilink connection, RasAdminPortClearStatistics resets the statistics for the specified port, The function also resets the cumulative statistics for the multilink connection. However, the function does not effect the individual statistics for other ports that are part of the multilink connection.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_PORT_STATISTICS, RasAdminPortGetInfo


RasAdminPortDisconnect

The RasAdminPortDisconnect function disconnects a port that is currently in use.

DWORD RasAdminPortDisconnect(
  const WCHAR *lpszServer,  // pointer to the server name
  const WCHAR *lpszPort  // pointer to the name of port on the server
);

Parameters

lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
Pointer to a null-terminated Unicode string that contains the name of the port on the server.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

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

Value | Meaning
ERROR_INVALID_PORT | The specified port is invalid.
NERR_UserNotFound | The port is not currently in use.

There is no extended error information for this function; do not call GetLastError.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions


RasAdminPortEnum

The RasAdminPortEnum function enumerates all ports on the specified RAS server. For each port on the server, the function returns a RAS_PORT_0 structure that contains information about the port.

DWORD RasAdminPortEnum(
  const WCHAR *lpszServer,  // pointer to the server name
  PRAS_PORT_0 *ppRasPort0,  // receives a pointer to an array of
                            // port information
  WORD *pcEntriesRead       // receives the number of ports
                            // enumerated
);

Parameters

lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
ppRasPort0
Pointer to a variable that receives a pointer to a buffer that contains an array of RAS_PORT_0 structures. When your application has finished with the memory, free it by calling the RasAdminFreeBuffer function.
pcEntriesRead
Pointer to a 16-bit variable that receives the total number of RAS_PORT_0 structures returned in the ppRasPort0 array.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
NERR_ItemNotFound | No ports could be enumerated. This could be because all configured ports on the server are currently being used for dialing out.

There is no extended error information for this function; do not call GetLastError.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_PORT_0, RasAdminFreeBuffer


RasAdminPortGetInfo

The RasAdminPortGetInfo function retrieves information about a specified port on a specified server.

DWORD RasAdminPortGetInfo(
  const WCHAR *lpszServer,  // pointer to the server name
  const WCHAR *lpszPort,  // pointer to the name of port on the
                          // server
  RAS_PORT_1 *pRasPort1,  // receives the state of the port
  RAS_PORT_STATISTICS *pRasStats,
                          // receives statistics about the port
  RAS_PARAMETERS **ppRasParams
                          // receives an array of media-specific
                          // parameters and values
);

Parameters

lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
Pointer to a null-terminated Unicode string that contains the name of the port on the server.
pRasPort1
Pointer to a RAS_PORT_1 structure that the function fills in with information about the state of the port.
pRasStats
Pointer to a RAS_PORT_STATISTICS structure that the function fills in with statistics about the port.
ppRasParams
Pointer to a variable that receives a pointer to an array of RAS_PARAMETERS structures. Each structure contains the name of a media-specific key, such as MAXCONNECTBPS, and its associated value. When your application is finished with the memory pointed to by *ppRasParams, free it by calling the RasAdminFreeBuffer function.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

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

Value | Meaning
ERROR_DEV_NOT_EXIST | The specified port is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to allocate a buffer for the ppRasParams array.

There is no extended error information for this function; do not call GetLastError.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminFreeBuffer


RasAdminReleaseIpAddress

The RasAdminReleaseIpAddress function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function to notify your DLL that the remote client was disconnected and that the IP address should be released.

VOID RasAdminReleaseIpAddress(
  WCHAR *lpszUserName,  // pointer to the name of the remote user
  WCHAR *lpszPortName,  // pointer to the name of the port
  IPADDR *pipAddress    // pointer to the IP address
);

Parameters

lpszUserName
Pointer to a null-terminated Unicode string that contains the name of a remote user for whom an IP address was previously obtained using the RasAdminGetIpAddressForUser function.
lpszPortName
Pointer to a null-terminated Unicode string that contains the name of the port on which the user specified by lpszUserName is connected.
pipAddress
Pointer to an IPADDR variable that contains the IP address returned for this user in a previous call to RasAdminGetIpAddressForUser.

Return Values

There is no extended error information for this function; do no call GetLastError.

Remarks

The RAS server calls your RasAdminReleaseIpAddress function only if your application returned TRUE in the bNotifyRelease parameter during the earlier call to RasAdminGetIpAddressForUser for the user specified by the lpszUserName parameter.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value Name | Value Data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS Administration DLL from a fictional company named Netwerks Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
    DisplayName  :  REG_SZ  :  Netwerks RAS Admin DLL
    DLLPath      :  REG_SZ  :  C:\nt\system32\ntwkadm.dll

The setup program for a RAS Administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasAdminGetIpAddressForUser


RasAdminServerGetInfo

The RasAdminServerGetInfo function gets the server configuration of a RAS server.

DWORD RasAdminServerGetInfo(
  const WCHAR *lpszServer,  // pointer to the name of the RAS server
  PRAS_SERVER_0 pRasServer0  // pointer to server information
);

Parameters

lpszServer
Pointer to a null-terminated Unicode string that contains the name of the Windows NT RAS server. If this parameter is NULL, the function returns information about the local computer. Specify the name with leading "\\" characters, in the form: \\servername.
pRasServer0
Pointer to a RAS_SERVER_0 structure that receives the number of ports configured on the server, the number of ports currently in use, and the server version number.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. Possible error codes include those returned by GetLastError for the CallNamedPipe function. There is no extended error information for this function; do not call GetLastError.

Remarks

To enumerate all RAS servers in a Windows NT domain, call the NetServerEnum function and specify SV_TYPE_DIALIN for the servertype parameter.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, NetServerEnum, RAS_SERVER_0


RasAdminUserGetInfo

The RasAdminUserGetInfo function gets the RAS permissions and callback phone number information for a specified user.

DWORD RasAdminUserGetInfo(
  const WCHAR *lpszUserAccountServer,
                         // pointer to the name of the user account
                         // server
  const WCHAR *lpszUser, // pointer to the name of the user
  PRAS_USER_0 pRasUser0  // receives the user's RAS information
);

Parameters

lpszUserAccountServer
Pointer to a null-terminated Unicode string that contains the name of the primary or backup domain controller that has the user account database. Use the RasAdminGetUserAccountServer function to get this server name.
lpszUser
Pointer to a null-terminated Unicode string that contains the name of the user for whom to get RAS information.
pRasUser0
Pointer to a RAS_USER_0 structure that receives the RAS data for the specified user.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
NERR_BufTooSmall | Insufficient memory to perform this function.

There is no extended error information for this function; do not call GetLastError.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserSetInfo


RasAdminUserSetInfo

The RasAdminUserSetInfo function sets the RAS permissions and call-back phone number for a specified user.

DWORD RasAdminUserSetInfo(
  const WCHAR *lpszUserAccountServer,
                               // pointer to the name of the user
                               // account server
  const WCHAR *lpszUser,       // pointer to the name of the user
  const PRAS_USER_0 pRasUser0  // pointer to the new RAS information
                               // for this user
);

Parameters

lpszUserAccountServer
Pointer to a null-terminated Unicode string that contains the name of the primary or backup domain controller that has the user account database. Use the RasAdminGetUserAccountServer function to get this server name.
lpszUser
Pointer to a null-terminated Unicode string that contains the name of the user for whom RAS information is to be set.
pRasUser0
Pointer to a RAS_USER_0 structure that contains the new RAS data for the specified user.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

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

Value | Description
ERROR_INVALID_DATA
 | The pRasUser0 buffer contains invalid data.
ERROR_INVALID_CALLBACK_NUMBER
 | The callback number specified in the pRasUser0 buffer contains invalid characters.
NERR_BufTooSmall
 | Insufficient memory to perform this function.

There is no extended error information for this function; do not call GetLastError.

Remarks

When setting the RAS permissions for a user, the bfPrivilege member of the RAS_USER_0 structure must specify at least one of the call-back flags. For example, to set a user's privileges to allow dial-in privilege but no call-back privilege, set bfPrivilege to RASPRIV_DialinPrivilege | RASPRIV_NoCallback.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.
Import Library: Use rassapi.lib.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserGetInfo


RasConnectionNotification

The RasConnectionNotification function specifies an event object that the system sets to the signaled state when a RAS connection is created or terminated.

DWORD RasConnectionNotification(
  HRASCONN hrasconn,  // handle to a RAS connection
  HANDLE hEvent,      // handle to an event object
  DWORD dwFlags       // type of event to receive notifications for
);

Parameters

hrasconn
Specifies a handle to the RAS connection for which to receive notifications. This can be a handle returned by the RasDial or RasEnumConnections function. If this parameter is INVALID_HANDLE_VALUE, you receive notifications for all RAS connections on the local computer.
hEvent
Specifies the handle of an event object. Use the CreateEvent function to create an event object.
dwFlags
Indicates the RAS event that causes the system to signal the event object specified by the hEvent parameter. This parameter can be a combination of the following values.
Value | Meaning
RASCN_Connection | If hrasconn is INVALID_HANDLE_VALUE, hEvent is signaled when any RAS connection is created.
RASCN_Disconnection | hEvent is signaled when the hrasconn connection is terminated. If hrasconn is a multilink connection, the event is signaled when all subentries are disconnected. If hrasconn is INVALID_HANDLE_VALUE, the event is signaled when any RAS connection is terminated.
RASCN_BandwidthAdded | Windows NT only: If hrasconn is a handle to a combined multilink connection, hEvent is signaled when a subentry is connected.
RASCN_BandwidthRemoved | Windows NT only: If hrasconn is a handle to a combined multilink connection, hEvent is signaled when a subentry is disconnected.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code.

Remarks

To determine when the event object is signaled, use any of the wait functions.

When the event is signaled, you can use other RAS functions, such as RasEnumConnections, to get more information about the RAS connection that was created or terminated.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, CreateEvent, RasEnumConnections


RasCreatePhonebookEntry

The RasCreatePhonebookEntry function creates a new phone-book entry. The function displays a dialog box in which the user types information for the phone-book entry.

Windows NT: The RasCreatePhonebookEntry function calls the RasEntryDlg function. Applications written for Windows NT version 4.0 should use RasEntryDlg.

DWORD RasCreatePhonebookEntry(
  HWND hwnd,  // handle to the parent window of the dialog box
  LPCTSTR lpszPhonebook
              // pointer to the full path and filename of the
              // phone-book file
);

Parameters

hwnd
Handle to the parent window of the dialog box.
lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the following error code:

Value | Description
ERROR_CANNOT_OPEN_PHONEBOOK
 | The phone book is corrupted or missing components.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasEditPhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasDeleteEntry

The RasDeleteEntry function deletes an entry from a phone book.

DWORD RasDeleteEntry(
  LPCTSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPCTSTR lpszEntry       // pointer to an entry name to delete
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing the name of an existing entry to be deleted.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is ERROR_INVALID_NAME.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasCreatePhonebookEntry, RasEnumEntries


RasDial

The RasDial function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user-authentication information.

DWORD RasDial(
  LPRASDIALEXTENSIONS lpRasDialExtensions,
                          // pointer to function extensions data
  LPCTSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPRASDIALPARAMS lpRasDialParams,
                          // pointer to calling parameters data
  DWORD dwNotifierType,   // specifies type of RasDial event handler
  LPVOID lpvNotifier,     // specifies a handler for RasDial events
  LPHRASCONN lphRasConn   // pointer to variable to receive
                          // connection handle
);

Parameters

lpRasDialExtensions
Windows NT: Points to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable. If you do not need to enable any of the extensions, set this parameter to NULL.

Windows 95: This parameter is ignored. On Windows 95, RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lpRasDialParams
Points to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMS structure's dwSize member to the sizeof(RASDIALPARAMS) to identify the version of the structure being passed.

dwNotifierType
Specifies the nature of the lpvNotifier parameter. If lpvNotifier is NULL, dwNotifierType is ignored. If lpvNotifier is not NULL, set dwNotifierType to one of the following values:
Value | Meaning
0xFFFFFFFF The lpvNotifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam is the equivalent of the rasconnstate parameter of RasDialFunc and RasDialFunc1, and lParam is the equivalent of the dwError parameter of RasDialFunc and RasDialFunc1.

The progress notification message uses a system registered message code. You can obtain the value of this message code as follows:

{UINT unMsg =

RegisterWindowMessageA( RASDIALEVENT );

if (unMsg == 0)

unMsg = WM_RASDIALEVENT;

}
0 | The lpvNotifier parameter points to a RasDialFunc callback function.
1 | The lpvNotifier parameter points to a RasDialFunc1 callback function.
2 | Windows NT: The lpvNotifier parameter points to a RasDialFunc2 callback function.

lpvNotifier
Specifies a window handle or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive RasDial event notifications. The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.

If this parameter is not NULL, RasDial sends the window a message, or calls the callback function, for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and communicates its progress via the window or callback function.

If lpvNotifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.

If lpvNotifier is not NULL, notifications to the window or callback function can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:

  • The connection is established. In other words, the RAS connection state is RASCS_Connected.
  • The connection fails. In other words, dwError is nonzero.
  • RasHangUp is called on the connection.

The callback notifications are made in the context of a thread captured during the initial call to RasDial.

lphRasConn
Points to a variable of type HRASCONN. You must set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.

Return Values

If the function succeeds, the immediate return value is zero. In addition, the function stores a handle to the RAS connection into the variable pointed to by lphRasConn.

If the function fails, the immediate return value is a nonzero error value, either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY.

Remarks

Errors that occur after the immediate return can be detected by RasGetConnectStatus. Data is available until an application calls RasHangUp to hang up the connection.

An application must eventually call RasHangUp whenever a non-NULL connection handle is stored into *lphRasConn. This applies even if RasDial returns a nonzero (error) value.

An application can safely call RasHangUp from a RasDial notifier callback function. If this is done, however, the hangup does not occur until the routine returns.

Windows NT: If the structure pointed to by lpRasDialExtensions enables RDEOPT_PausedStates, the RasDial function pauses whenever it enters a state in which the RASCS_PAUSED bit is set to one. To restart RasDial from such a paused state, call RasDial again, passing the connection handle returned from the original RasDial call in *lphRasConn. The same notifier used in the original RasDial call must be used when restarting from a paused state.

To specify that RasDial should enter a RASCS_CallbackSetByCaller state, set lpRasDialParams->szCallbackNumber to "*" on the initial call to RasDial. When your notification handler is called with this state, you can set the the callback number to a number supplied by the user.

Windows 95: Windows 95 does not support the RASCS_CallbackSetByCaller state or any of the other paused states.

Windows CE: The dialExtensions parameter is ignored and should be set to NULL. RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.

The lpszPhonebook parameter must be set to NULL. Phone book entries are stored in the registry rather than a phone-book file.

The dwNotiferType parameter must be set to 0xFFFFFFFF, specifying the lpvNotifier parameter is a handle to the window receiving progress notification messages.

The szCallBackNumber and szPhoneNumber members of lpRasDialParam are not used and should be set to NULL.

RasDial will not automatically display the logon dialog box. This is currently done through the Remote Networking application. Applications are responsible for getting the information from the user.

Windows CE does not support the ERROR_CANNOT_FIND_PHONEBOOK_ENTRY return value.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDialDlg, RasDialFunc, RasDialFunc1, RasDialFunc2, RasGetConnectStatus, RasHangUp, RASDIALEXTENSIONS, RASDIALPARAMS, WM_RASDIALEVENT


RasDialDlg

The RasDialDlg function tries to establish a RAS connection using a specified phone-book entry and the credentials of the logged-on user. The function displays a stream of dialog boxes that indicate the state of the connection operation.

BOOL RasDialDlg(
  LPTSTR lpszPhonebook,   // pointer to the full path and filename of
                          // the phone-book file
  LPTSTR lpszEntry,       // pointer to the name of the phone-book
                          // entry to dial
  LPTSTR lpszPhoneNumber, // pointer to replacement phone number to
                          // dial
  LPRASDIALDLG lpInfo     // pointer to a structure that contains
                          // additional parameters
);

Parameters

lpszPhonebook
Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of the phone-book entry to dial.
lpszPhoneNumber
Pointer to a null-terminated string that contains a phone number that overrides the numbers stored in the phone-book entry. If this parameter is NULL, RasDialDlg uses the numbers in the phone-book entry.
lpInfo
Pointer to a RASDIALDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASDIALDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the function establishes a RAS connection, the return value is a nonzero value.

If an error occurs, or if the user selects the Cancel button during the dialing operation, the return value is zero. If an error occurs, the dwError member of the RASDIALDLG structure returns a nonzero system or RAS error code.

Remarks

The RasDialDlg function displays a stream of dialog boxes that are similar to the dialog boxes that main Dial-Up Networking dialog box displays when the user selects the Dial button. The RasDialDlg function is useful for applications in which you want to display a standard user interface for a connection operation without presenting the main phone-book dialog box. For example, the RAS AutoDial service uses this function to establish a connection using the phone-book entry associated with a remote address.

The RasDialDlg function displays dialog boxes during the connection operation to provide feedback to the user about the progress of the operation. For example, the dialog boxes might indicate when the operation is dialing, when it is authenticating the user's credentials on the remote server, and so on. The dialog boxes also provide a Cancel button for the user to terminate the operation.

RasDialDlg returns when the connection is established, or when the user cancels the operation.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASDIALDLG, RasPhonebookDlg


RasDialFunc

The RasDialFunc function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a RAS connection process.

VOID WINAPI RasDialFunc(
  UINT unMsg,    // type of event that has occurred
  RASCONNSTATE rasconnstate,
                 // connection state about to be entered
  DWORD dwError  // error that may have occurred
);

Parameters

unMsg
Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rasconnstate
Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
Indicates the error that has occurred, or zero if no error has occurred.

RasDial calls RasDialFunc with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDialFunc is called again with a nonzero dwError value.

Return Values

None.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc callback function. For that reason, your RasDialFunc implementation should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

Your RasDialFunc implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc callback function. You can call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note For convenience, RasHangUp can be called from within a RasDialFunc callback function. However, much of the hang-up processing occurs after the RasDialFunc callback function has returned.

RasDialFunc is a placeholder for the application-defined or library-defined function name.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: User-defined.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCONNSTATE, RasDial, RasDialFunc1, RasDialFunc2, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc1

A RasDialFunc1 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc1 function is comparable to a RasDialFunc function, but is enhanced by the addition of two parameters: a handle to the RAS connection, and an extended error code.

VOID WINAPI RasDialFunc1(
  HRASCONN hrasconn,  // handle to RAS connection
  UINT unMsg,         // type of event that has occurred
  RASCONNSTATE rascs, // connection state about to be entered
  DWORD dwError,      // error that may have occurred
  DWORD dwExtendedError
                      // extended error information for some errors
);

Parameters

hrasconn
Provides a handle to the RAS connection, as returned by RasDial.
unMsg
Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rascs
Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
Specifies the error that has occurred. If no error has occurred, dwError is zero.

RasDial calls RasDialFunc1 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc1 again with a nonzero dwError value.

In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError
Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.

The contents of dwExtendedError are defined for values of dwError as follows:
dwError | dwExtendedError
ERROR_SERVER_NOT_RESPONDING | Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR | Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL | Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA | Specifies a routing error code, which is a RAS error.

Return Values

None.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc1 callback function. For that reason, your RasDialFunc1 implementation should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc1 function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

Your RasDialFunc1 implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc1 callback function. You can call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note that, for convenience, RasHangUp can be called from within a RasDialFunc1 callback function. However, much of the hang-up processing occurs after the RasDialFunc1 callback function has returned.

RasDialFunc1 is a placeholder for the application-defined or library-defined function name.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: User-defined.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDial, RasDialFunc, RasDialFunc2, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc2

A RasDialFunc2 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc2 function is similar to the RasDialFunc1 callback function, except that it provides additional information for multilink connections.

DWORD WINAPI RasDialFunc2(
  DWORD dwCallbackId,    // user-defined value specified in RasDial
                         // call
  DWORD dwSubEntry,      // subentry index in multilink connection
  HRASCONN hrasconn,     // handle to RAS connection
  UINT unMsg,            // type of event that has occurred
  RASCONNSTATE rascs,    // connection state about to be entered
  DWORD dwError,         // error that may have occurred
  DWORD dwExtendedError  // extended error information for some
                         // errors
);

Parameters

dwCallbackId
Provides an application-defined value that was specified in the dwCallbackId member of the RASDIALPARAMS structure passed to RasDial.
dwSubEntry
Specifies a subentry index for the phone-book entry associated with this connection. This value indicates the subentry that generated this call to your RasDialFunc2 callback function.
hrasconn
Provides a handle to the RAS connection, as returned by RasDial.
unMsg
Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rascs
Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
Specifies the error that has occurred. If no error has occurred, dwError is zero.

The RasDial function calls RasDialFunc2 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc2 again with a nonzero dwError value.

In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError
Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.

The contents of dwExtendedError are defined for values of dwError as follows:
dwError | dwExtendedError
ERROR_SERVER_NOT_RESPONDING | Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR | Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL | Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA | Specifies a routing error code, which is a RAS error.

Return Values

If the RasDialFunc2 function returns a nonzero value, RasDial continues to send callback notifications.

If the RasDialFunc2 function returns zero, RasDial stops sending callback notifications for all subentries.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc2 callback function. For that reason, your RasDialFunc2 implementation should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc2 function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

Your RasDialFunc2 implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc2 callback function. You can call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note Gor convenience, RasHangUp can be called from within a RasDialFunc2 callback function. However, much of the hang-up processing occurs after the RasDialFunc2 callback function has returned.

RasDialFunc2 is a placeholder for the application-defined or library-defined function name.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: User-defined.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasEditPhonebookEntry

The RasEditPhonebookEntry function edits an existing phone-book entry. The function displays a dialog box in which the user can modify the existing information.

Windows NT: The RasEditPhonebookEntry function calls the RasEntryDlg function. Applications written for Windows NT version 4.0 should use RasEntryDlg.

DWORD RasEditPhonebookEntry(
  HWND hwnd,             // handle to the parent window of the dialog
                         // box
  LPCTSTR lpszPhonebook, // pointer to the full path and filename of
                         // the phone-book file
  LPCTSTR lpszEntryName  // pointer to the phone-book entry name
);

Parameters

hwnd
Handle to the parent window of the dialog box.
lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lpszEntryName
Points to a null-terminated string that specifies the name of an existing entry in the phone-book file.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes:

Value | Description
ERROR_BUFFER_INVALID
 | The phone-book entry buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK
 | The phone book is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
 | The phone-book entry does not exist.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasCreatePhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasEntryDlg

The RasEntryDlg function displays modal property sheets that allow a user to manipulate phone-book entries. If editing or copying an existing phone-book entry, the function displays a phone-book entry property sheet. The RasEntryDlg function returns when the user closes the property sheet.

BOOL RasEntryDlg(
  LPTSTR lpszPhonebook, // pointer to the full path and filename of
                        // the phone-book file
  LPTSTR lpszEntry,     // pointer to the name of the phone-book
                        // entry to edit, copy, or create
  LPRASENTRYDLG lpInfo  // pointer to a structure that contains
                        // additional parameters
);

Parameters

lpszPhonebook
Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of the phone-book entry to edit, copy, or create.

If you are editing or copying an entry, this parameter is the name of an existing phone-book entry. If you are copying an entry, set the RASEDFLAG_CloneEntry flag in the dwFlags member of the RASENTRYDLG structure.

If you are creating an entry, this parameter is a default new entry name that the user can change. If this parameter is NULL, the function provides a default name. If you are creating an entry, set the RASEDFLAG_NewEntry flag in the dwFlags member of the RASENTRYDLG structure.

lpInfo
Pointer to a RASENTRYDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASENTRYDLG). Use the dwFlags member to indicate whether you are creating, editing, or copying an entry. If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user creates, copies, or edits a phone-book entry, the return value is a nonzero value.

If an error occurs, or if the user cancels the operation, the return value is zero. If an error occurs, the dwError member of the RASENTRYDLG structure returns a nonzero system error code or RAS error code.

Remarks

The RasCreatePhonebookEntry and RasEditPhonebookEntry functions call the RasEntryDlg function.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasCreatePhonebookEntry, RasEditPhonebookEntry, RASENTRYDLG


RasEnumAutodialAddresses

The RasEnumAutodialAddresses function returns a list of all addresses in the AutoDial mapping database.

DWORD RasEnumAutodialAddresses(
  LPTSTR *lppAddresses,  // pointer to buffer that receives network
                         // address strings
  LPDWORD lpdwcbAddresses,  // pointer to size, in bytes, of the
                            // buffer
  LPDWORD lpdwcAddresses // pointer to number of strings returned
);

Parameters

lppAddresses
Pointer to an array of string pointers, with additional space for the storage of the strings themselves at the end of the buffer. Each string is the name of an address in the AutoDial mapping database.

If lppAddresses is NULL, RasEnumAutodialAddresses sets the lpdwcbAddresses and lpdwcAddresses parameters to indicate the required size, in bytes, and the number of address entries in the database.

lpdwcbAddresses
Pointer to a variable that contains the size, in bytes, of the buffer specified by the lppAddresses parameter. On return, the function sets this variable to the number of bytes returned, or the number of bytes required if the buffer is too small.
lpdwcAddresses
Pointer to a variable that receives the number of address strings returned in the lppAddresses buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | NULL was passed for the lpdwcbAddresses or lpdwcAddresses parameter.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASAUTODIALENTRY, RasGetAutodialAddress, RasSetAutodialAddress


RasEnumConnections

The RasEnumConnections function lists all active RAS connections. It returns each connection's handle and phone-book entry name.

DWORD RasEnumConnections(
  LPRASCONN lprasconn,  // buffer to receive connections data
  LPDWORD lpcb,         // size in bytes of buffer
  LPDWORD lpcConnections
                        // number of connections written to buffer
);

Parameters

lprasconn
Points to a buffer that receives an array of RASCONN structures, one for each RAS connection. Before calling the function, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.
lpcb
Points to a variable that contains the size, in bytes, of the buffer specified by lprasconn. On return, the function sets this variable to the number of bytes required to enumerate the RAS connections.
lpcConnections
Points to a variable that the function sets to the number of RASCONN structures written to the buffer specified by lprasconn.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

Remarks

If a connection was made without specifying a phone-book entry name, the information returned for that connection will give the connection phone number preceded by ".".

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCONN, RasEnumEntries, RasGetConnectStatus


RasEnumDevices

The RasEnumDevices function returns the name and type of all available RAS-capable devices.

DWORD RasEnumDevices(
  LPRASDEVINFO lpRasDevInfo,  // buffer to receive information about
                              // RAS devices
  LPDWORD lpcb,               // size, in bytes, of the buffer
  LPDWORD lpcDevices          // receives the number of entries
                              // written to the buffer
);

Parameters

lpRasDevInfo
Pointer to a buffer that receives an array of RASDEVINFO structures, one for each RAS-capable device. Before calling the function, set the dwSize member of the first RASDEVINFO structure in the buffer to sizeof(RASDEVINFO) to identify the version of the structure.
lpcb
Pointer to a variable that contains the size, in bytes, of the lpRasDevInfo buffer. On return, the function sets this variable to the number of bytes required to enumerate the devices.

To determine the required buffer size, call RasEnumDevices with the lpRasDevInfo parameter set to NULL and the variable pointed to by lpcb set to zero. The function returns the required buffer size in the variable pointed to by lpcb.

lpcDevices
Pointer to a variable that the function sets to the number of RASDEVINFO structures written to the lpRasDevInfo buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero RAS error value or one of following error codes.

Value | Meaning
ERROR_BUFFER_TOO_SMALL | The lpRasDevInfo buffer is not large enough. The function returns the required buffer size in the variable pointed to by lpcb.
ERROR_NOT_ENOUGH_MEMORY | Indicates insufficient memory.
ERROR_INVALID_PARAMETER | Indicates an invalid parameter value.
ERROR_INVALID_USER_BUFFER | The address or buffer specified by lpRasDevInfo is invalid.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASDEVINFO


RasEnumEntries

The RasEnumEntries function lists all entry names in a remote access phone book.

DWORD RasEnumEntries (
  LPCTSTR reserved,       // reserved, must be NULL
  LPTCSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPRASENTRYNAME lprasentryname,
                          // buffer to receive phone-book entries
  LPDWORD lpcb,           // size in bytes of buffer
  LPDWORD lpcEntries      // number of entries written to buffer
);

Parameters

reserved
Reserved; must be NULL.
lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasentryname
Points to a buffer that receives an array of RASENTRYNAME structures, one for each phone-book entry. Before calling the function, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.
lpcb
Points to a variable that contains the size, in bytes, of the buffer specified by lprasentryname. On return, the function sets this variable to the number of bytes required to successfully complete the call.
lpcEntries
Points to a variable that the function, if successful, sets to the number of phone-book entries written to the buffer specified by lprasentryname.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASENTRYNAME, RasEnumConnections


RasGetAutodialAddress

The RasGetAutodialAddress function retrieves information about all the AutoDial entries associated with a network address in the AutoDial mapping database.

DWORD RasGetAutodialAddress(
  LPCTSTR lpszAddress,   // pointer to a network address string
  LPDWORD lpdwReserved,  // reserved; must be NULL
  LPRASAUTODIALENTRY lpAutoDialEntries,
                       // pointer to buffer for AutoDial entry data
  LPDWORD lpdwcbAutoDialEntries,
                       // pointer to size, in bytes, of buffer
  LPDWORD lpdwcAutoDialEntries
                       // pointer to number of entries returned
);

Parameters

lpszAddress
Pointer to a null-terminated string that specifies the address for which information is requested. This can be an IP address ("127.95.1.4"), Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").
lpdwReserved
Reserved; must be NULL.
lpAutoDialEntries
Pointer to a buffer that receives an array of RASAUTODIALENTRY structures, one for each AutoDial entry associated with the address specified by the lpszAddress parameter. Before calling RasGetAutodialAddress, set the dwSize member of the first RASAUTODIALENTRY structure in the buffer to sizeof(RASAUTODIALENTRY) to identify the version of the structure.

If lpAutoDialEntries is NULL, RasGetAutodialAddress sets the lpdwcbAutoDialEntries and lpdwcAutoDialEntries parameters to indicate the required buffer size, in bytes, and the number of AutoDial entries.

lpdwcbAutoDialEntries
Pointer to a variable that contains the size, in bytes, of the lpAutoDialEntries buffer. On return, the function sets this variable to the number of bytes returned, or the number of bytes required if the buffer is too small.
lpdwcAutoDialEntries
Pointer to a variable that receives the number of structure elements returned in the lpAutoDialEntries buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_XXX_NOT_FOUND | The address was not found in the mapping database.
ERROR_INVALID_SIZE | The dwSize member of the RASAUTODIALENTRY structure is an invalid value.
ERROR_INVALID_PARAMETER | The lpszAddress, lpdwcbAutoDialEntries, or lpdwcAutoDialEntries parameter was NULL.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASAUTODIALENTRY, RasEnumAutodialAddresses, RasSetAutodialAddress


RasGetAutodialEnable

The RasGetAutodialEnable function indicates whether the AutoDial feature is enabled for a specified TAPI dialing location. For more information about TAPI dialing locations, see the Win32 Telephony (TAPI) Programmer's Reference.

DWORD RasGetAutodialEnable(
  DWORD dwDialingLocation,
                     // identifier of the TAPI dialing location
  LPBOOL lpfEnabled  // pointer to variable that receives AutoDial
                     // state for this location
);

Parameters

dwDialingLocation
Specifies the identifier of a TAPI dialing location.
lpfEnabled
Pointer to a BOOL variable that receives a nonzero value if AutoDial is enabled for the specified dialing location, or zero if it is not enabled.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero value.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasSetAutodialEnable


RasGetAutodialParam

The RasGetAutodialParam function retrieves the value of an AutoDial parameter.

DWORD RasGetAutodialParam(
  DWORD dwKey,      // indicates the parameter to retrieve
  LPVOID lpvValue,  // pointer to a buffer that receives the value
  LPDWORD lpdwcbValue
                    // size, in bytes, of the buffer
);

Parameters

dwKey
Indicates the AutoDial parameter to retrieve. This parameter can be one of the following values.
Value | Meaning
RASADP_DisableConnectionQuery | The lpvValue parameter returns a DWORD value. If this value is zero (the default), AutoDial displays a dialog box to query the user before creating a connection. If this value is 1, and the AutoDial database has the phone-book entry to dial, AutoDial creates a connection without displaying the dialog box.
RASADP_LoginSessionDisable | The lpvValue parameter returns a DWORD value. If this value is 1, the system disables all AutoDial connections for the current logon session. If this value is zero (the default), AutoDial connections are enabled. The AutoDial system service changes this value to zero when a new user logs on to the workstation.
RASADP_SavedAddressesLimit | The lpvValue parameter returns a DWORD value that indicates the maximum number of addresses that AutoDial stores in the registry. AutoDial first stores addresses that it used to create an AutoDial connection; then it stores addresses that it learned after a RAS connection was created. Addresses written using the RasSetAutodialAddress function are always saved, and are not included in calculating the limit. The default value is 100.
RASADP_FailedConnectionTimeout | The lpvValue parameter returns a DWORD value that indicates a timeout value, in seconds. When an AutoDial connection attempt fails, the AutoDial system service disables subsequent attempts to reach the same address for the timeout period. This prevents AutoDial from displaying multiple connection dialog boxes for the same logical request by an application. The default value is 5.
RASADP_ConnectionQueryTimeout | The lpvValue parameter points to a DWORD value that indicates a timeout value, in seconds. Before attempting an AutoDial connection, the system will display a dialog asking the user to confirm that the system should dial. The dialog has a countdown timer that will terminate the dialog with a "Do not dial" selection if the user takes no action. The DWORD value pointed to by lpvValue specifies the initial time on this countdown timer.

lpvValue
Pointer to a buffer that receives the value for the specified parameter.
lpdwcbValue
Pointer to a DWORD value. On input, set this value to indicate the size, in bytes, of the lpvValue buffer. On output, this value indicates the actual size of the value written to the buffer.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_PARAMETER | The dwKey or lpvValue parameter is invalid.
ERROR_INVALID_SIZE | The size specified by the lpdwcbValue is too small.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasSetAutodialAddress, RasSetAutodialParam


RasGetConnectStatus

The RasGetConnectStatus function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call has completed.

DWORD RasGetConnectStatus(
  HRASCONN hrasconn,  // handle to RAS connection of interest
  LPRASCONNSTATUS lprasconnstatus
                      // buffer to receive status data
);

Parameters

hrasconn
Identifies the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.
lprasconnstatus
Points to a RASCONNSTATUS structure that the function fills with status information. Before calling the function, an application must set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCONNSTATUS, RasDial, RasEnumConnections


RasGetCountryInfo

The RasGetCountryInfo function retrieves country-specific dialing information from the Windows Telephony list of countries.

For more information about country-specific dialing information and TAPI country identifiers, see the Win32 Telephony (TAPI) Programmer's Reference.

DWORD RasGetCountryInfo(
  LPRASCTRYINFO lpRasCtryInfo,
                    // buffer that receives country information
  LPDWORD lpdwSize  // size, in bytes, of the buffer
);

Parameters

lpRasCtryInfo
Pointer to a RASCTRYINFO structure that receives the country-specific dialing information followed by additional bytes for a country description string. Before calling the function, set the dwSize member of the structure to sizeof(RASCTRYINFO) to identify the version of the structure. You must also set the dwCountryId member to the TAPI country identifier of the country for which to get information.

The size of the buffer should be at least 256 bytes.

lpdwSize
Pointer to a variable that contains the size, in bytes, of the buffer pointed to by the lpRasCtryInfo parameter. On return, the function sets this variable to the number of bytes required.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_USER_BUFFER | The address or buffer specified by lpRasCtryInfo is invalid.
ERROR_INVALID_PARAMETER | The dwCountryId member of the structure pointed to by lpRasCtryInfo was not a valid value.
ERROR_BUFFER_TOO_SMALL | The size of the lpRasCtryInfo buffer specified by the lpdwSize parameter was not large enough to store the information for the country identified by the dwCountryId member. The function returns the required buffer size in the variable pointed to by lpdwSize.
ERROR_TAPI_CONFIGURATION | TAPI subsystem information was corrupted.

Remarks

To enumerate information for all countries in the Windows Telephony list, set the dwCountryId member of the RASCTRYINFO structure to 1 in the initial RasGetCountryInfo call. This causes the function to return information for the first country in the list. The value returned in the dwNextCountryId member is the country identifier of the next country in the list. Use this value in repeated calls to RasGetCountryInfo until dwNextCountryID returns zero, indicating the last country in the list.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCTRYINFO


RasGetCredentials

The RasGetCredentials function retrieves the user credentials associated with a specified RAS phone-book entry.

DWORD RasGetCredentials(
  LPCTSTR lpszPhonebook,            // pointer to the full path and
                                    // filename of a phone-book file
  LPCTSTR lpszEntry,                // pointer to the name of a
                                    // phone-book entry
  LPRASCREDENTIALS lpCredentials    // pointer to structure that
                                    // receives credentials
);

Parameters

lpszPhonebook
Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of a phone-book entry.
lpCredentials
Pointer to a RASCREDENTIALS structure that receives the user credentials associated with the specified phone-book entry. Before calling RasGetCredentials, set the dwSize member of the structure to sizeof(RASCREDENTIALS), and set the dwMask member to indicate the credential information to retrieve. When the function returns, dwMask indicates the members that were successfully retrieved.

Return Values

If the function succeeds the return value is zero.

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

Value | Meaning
ERROR_CANNOT_OPEN_PHONEBOOK | The specified phone book cannot be found.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The specified entry does not exist in the phone book.
ERROR_INVALID_PARAMETER | The lpCredentials parameter was NULL.
ERROR_INVALID_SIZE | The dwSize member of the RASCREDENTIALS structure is an unrecognized value.

Remarks

The RasGetCredentials function retrieves the credentials of the last user to successfully connect using the specified phone-book entry, or the credentials subsequently specified in a call to the RasSetCredentials function for the phone-book entry.

The RasGetCredentials function retrieves the user credentials that are stored securely for the specified phone-book entry. This function is the preferred way of securely retrieving the credentials associated with a RAS phone book entry. RasGetCredentials supersedes the RasGetEntryDialParams function, which may not be supported in future releases of Windows NT.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCREDENTIALS, RasGetEntryDialParams, RasSetCredentials


RasGetEntryDialParams

The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phone-book entry.

DWORD RasGetEntryDialParams(
  LPCTSTR lpszPhonebook,  // pointer to the full path and filename
                          // of the phone-book file
  LPRASDIALPARAMS lprasdialparams,
                          // pointer to a structure that receives
                          // the connection parameters
  LPBOOL lpfPassword      // indicates whether the user's password
                          // was retrieved
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasdialparams
Pointer to a RASDIALPARAMS structure. On input, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phone-book entry. On output, the structure receives the connection parameters associated with the specified phone-book entry.

Note that the szPhoneNumber member of the structure does not receive the phone number associated with the phone-book entry. To get the phone number associated with a phone-book entry, call the RasGetEntryProperties function.

lpfPassword
Points to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The function sets this flag to TRUE if the user's password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lprasdialparams.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes:

Value | Description
ERROR_BUFFER_INVALID
 | The lprasdialparams or lpfPassword pointer is invalid, or the lprasdialparams buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK
 | The phone book is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
 | The phone-book entry does not exist.

Remarks

Windows CE: The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDial, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasSetEntryDialParams


RasGetEntryProperties

The RasGetEntryProperties function retrieves the properties of a phone-book entry.

DWORD RasGetEntryProperties(
  LPCTSTR lpszPhonebook,   // pointer to full path and filename of
                           // phone-book file
  LPCTSTR lpszEntry,       // pointer to an entry name
  LPRASENTRY lpRasEntry,   // buffer that receives entry information
  LPDWORD lpdwEntryInfoSize,  // size, in bytes, of the lpRasEntry
                              // buffer
  LPBYTE lpbDeviceInfo,    // buffer that receives device-specific
                           // configuration information
  LPDWORD lpdwDeviceInfoSize  // size, in bytes, of the
                              // lpbDeviceInfo buffer
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing an existing entry name. If you specify an empty string, "", the function returns default values in the buffers pointed to by the lpRasEntry and lpbDeviceInfo parameters.
lpRasEntry
Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one. The structure receives the connection data associated with the phone-book entry specified by the lpszEntry parameter. Before calling the function, set the dwSize member of the structure to sizeof(RASENTRY) to identify the version of the structure. This parameter can be NULL.
lpdwEntryInfoSize
Pointer to a variable that contains the size, in bytes, of the lpRasEntry buffer. On return, the function sets this variable to the number of bytes required. This parameter can be NULL if the lpRasEntry parameter is NULL.

To determine the required buffer size, call RasGetEntryProperties with lpRasEntry set to NULL and *lpdwEntryInfoSize set to zero. The function returns the required buffer size in *lpdwEntryInfoSize.

lpbDeviceInfo
Pointer to a buffer that receives device-specific configuration information. This is opaque TAPI device configuration information that you should not manipulate directly. This parameter can be NULL. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer's Reference.

Windows NT: This parameter is unused. The calling function should set this parameter to NULL.

lpdwDeviceInfoSize
Pointer to a variable that contains the size, in bytes, of the buffer specified by the lpbDeviceInfo parameter. On return, the function sets this variable to the number of bytes required. This parameter can be NULL if the lpbDeviceInfo parameter s NULL.

To determine the required buffer size, call RasGetEntryProperties with lpbDeviceInfo set to NULL and *lpdwDeviceInfoSize set to zero. The function returns the required buffer size in *lpdwDeviceInfoSize.

Windows NT: This parameter is unused. The calling function should set this parameter to NULL.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.
ERROR_INVALID_SIZE | The value of the dwSize member of the lpRasEntry is too small.
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_BUFFER_TOO_SMALL | The buffer size indicated in lpdwEntryInfoSize is too small.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or is missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Remarks

Windows CE: For Windows CE version 1.0, the lpbDeviceInfo and lpdwDeviceInfoSize parameters are ignored and should be set to NULL. To retrieve device specific configuration information use the RasGetEntryDevConfig function.

For Windows CE version 2.0 and later, device configuration information can be retrieved by using the lpbDeviceInfo and lpdwDeviceInfoSize parameters.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASENTRY, RasSetEntryProperties


RasGetErrorString

The RasGetErrorString function obtains an error message string for a specified RAS error value.

DWORD RasGetErrorString(
  UINT uErrorValue,        // error to get string for
  LPTSTR lpszErrorString,  // buffer to hold error string
  DWORD cBufSize           // size, in characters, of buffer
);

Parameters

uErrorValue
Specifies the error value of interest. These are values returned by one of the RAS functions: those listed in the RAS header file.
lpszErrorString
Points to a buffer that the function will write the error string to. This parameter must not be NULL.
cBufSize
Specifies the size, in characters, of the buffer pointed to by lpszErrorString.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value. This value is ERROR_INVALID_PARAMETER or the GetLastError value returned from the functions GlobalAlloc or LoadString. The function does not set a thread's last error information; that is, there is no GetLastError information set by the RasGetErrorString function.

Remarks

There is no way to determine in advance the exact size in characters of an error message, and thus the size of buffer required. Error messages will generally be 80 characters or fewer in size; a buffer size of 256 characters will always be adequate. A buffer of insufficient size causes the RasGetErrorString function to fail, returning ERROR_INSUFFICIENT_BUFFER. Note that buffer sizes are specified in characters, not bytes; thus, the Unicode version of RasGetErrorString requires a 512 byte buffer to guarantee that every error message will fit.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, GlobalAlloc, LoadString


RasGetProjectionInfo

The RasGetProjectionInfo function obtains information about a remote access projection operation for a specified remote access component protocol.

DWORD RasGetProjectionInfo(
  HRASCONN hrasconn,            // handle that specifies remote
                                // access connection of interest
  RASPROJECTION rasprojection,  // specifies type of projection
                                // information to obtain
  LPVOID lpprojection,          // points to buffer that receives
                                // projection information
  LPDWORD lpcb                  // points to variable that specifies
                                // buffer size
);

Parameters

hrasconn
Handle to the remote access connection of interest. An application obtains a RAS connection handle from the RasDial or RasEnumConnections function.
rasprojection
A RASPROJECTION enumerated type value that specifies the protocol of interest.
lpprojection
Points to a buffer that will receive the information specified by the rasprojection parameter. The information will be in a structure appropriate to the rasprojection value:
rasprojection value | Data structure
RASP_Amb | RASAMB
RASP_PppNbf | RASPPPNBF
RASP_PppIpx | RASPPPIPX
RASP_PppIp | RASPPPIP

lpcb
Points to a variable that, on entry, specifies the size in bytes of the buffer pointed to by lpprojection. On exit, this variable contains the size of buffer needed to contain the specified projection information.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is an error code. The function may return a nonzero RAS error code, or one of the following error codes:

Value | Meaning
ERROR_BUFFER_TOO_SMALL | The buffer pointed to by lpprojection is not large enough to contain the requested information.
ERROR_INVALID_HANDLE | The hrasconn parameter is not a valid handle.
ERROR_INVALID_PARAMETER | One of the parameters is invalid.
ERROR_INVALID_SIZE | The dwSize member of the structure pointed to by lpprojection specifies an invalid size.
ERROR_PROTOCOL_NOT_CONFIGURED | The control protocol for which information was requested neither succeeded nor failed, because the connection's phone-book entry did not require that an attempt to negotiate the protocol be made. This is a RAS error code.

Remarks

Remote access projection is the process whereby a remote access server and a remote client negotiate network protocol-specific information. A remote access server uses this network protocol-specific information to represent a remote client on the network.

Windows NT: Remote access projection information is not available until the operating system has executed the RasDial RASCS_Projected state on the remote access connection. If RasGetProjectionInfo is called prior to the RASCS_Projected state, it returns ERROR_PROJECTION_NOT_COMPLETE.

Windows 95: Windows 95 Dial-Up Networking does not support the RASCS_Projected state. The projection phase may be done during the RASCS_Authenticate state. If the authentication is successful, the connection operation proceeds to the RASCS_Authenticated state, and projection information is available for successfully configured protocols. If RasGetProjectionInfo is called prior to the RASCS_Authenticated state, it returns ERROR_PROTOCOL_NOT_CONFIGURED.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASAMB, RasDial, RasEnumConnections, RASPPPNBF, RASPPPIPX, RASPPPIP, RASPROJECTION


RasGetSubEntryHandle

The RasGetSubEntryHandle function retrieves a connection handle for a specified subentry of a multilink connection.

DWORD RasGetSubEntryHandle(
  HRASCONN hrasconn,
  DWORD dwSubEntry,
  LPHRASCONN lphrasconn
);

Parameters

hrasconn
Specifies an HRASCONN connection handle returned by the RasDial function for a multilink phone-book entry.
dwSubEntry
Specifies a valid subentry index for the phone-book entry.
lphrasconn
Pointer to an HRASCONN variable that receives a connection handle that represents the subentry connection.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_HANDLE | The hrasconn connection handle does not represent a connected phone-book entry.
ERROR_PORT_NOT_OPEN | The hrasconn and dwSubEntry parameters are valid, but the specified subentry is not connected.
ERROR_NO_MORE_ITEMS | The value specified by dwSubEntry exceeds the maximum number of subentries for the phone-book entry.

Remarks

The connection handle specified in the hrasconn parameter refers to the entire multilink connection, but the connection handle returned in the *lphrasconn parameter refers only to the subentry connection. You can use the subentry connection handle in any function that accepts an hrasconn parameter, including the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfo functions. The projection information returned by RasGetProjectionInfo for a multilink entry is the same for the each of the subentry connection handles as it is for the main connection handle.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasDial, RasGetConnectStatus, RasGetProjectionInfo, RasHangUp


RasGetSubEntryProperties

The RasGetSubEntryProperties function retrieves information about a subentry for a specified phone-book entry.

DWORD RasGetSubEntryProperties(
  LPCTSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPCTSTR lpszEntry,      // pointer to an entry name
  DWORD dwSubEntry,       // index of the subentry
  LPRASSUBENTRY lpRasSubEntry,
                          // pointer to structure that receives
                          // information about subentry
  LPDWORD lpdwcb,          // size, in bytes, of the structure
  LPBYTE  lpbDeviceConfig, // pointer to TAPI device configuration
  LPDWORD lpcbDeviceConfig // pointer to size of device configuration
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing the name of an existing entry in the phone book.
dwSubEntry
Specifies the one-based index of the subentry.
lpRasSubEntry
Pointer to a RASSUBENTRY structure followed by additional bytes for the alternate phone number list, if there is one. The structure receives the information about the specified subentry. Before calling the function, set the dwSize member of the structure to sizeof(RASSUBENTRY) to identify the version of the structure. This parameter can be NULL.
lpdwcb
Pointer to a variable that contains the size, in bytes, of the lpRasSubEntry buffer. On return, the function sets this variable to the number of bytes returned, or the number of bytes required if the buffer is too small. This parameter can be NULL if lpRasSubEntry is NULL.
lpbDeviceConfig
Pointer to a TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter. For more information about TAPI device configuration blocks, see the function lineGetDevConfig.
lpcbDeviceConfig
Pointer to a DWORD to receive the size of the TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasSubEntry is invalid.
ERROR_BUFFER_TOO_SMALL | The lpRasSubEntry buffer is too small. The lpdwcb variable receives the required buffer size.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or is missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Remarks

A RAS phone-book entry can have zero or more subentries, each minimally consisting of a device and a phone number. A phone-book entry with multiple subentries can be configured to dial the first available or all subentries when the entry is dialed.

Use the RasGetEntryProperties function to retrieve a RASENTRY structure containing information about the subentries of a phone-book entry. The dwSubEntries member indicates the number of subentries and the dwDialMode member indicates the dialing configuration.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasGetEntryProperties, RASENTRY, RasSetSubEntryProperties, RASSUBENTRY


RasHangUp

The RasHangUp function terminates a remote access connection. The connection is specified with a RAS connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

DWORD RasHangUp(
  HRASCONN hrasconn   // handle to the RAS connection to hang up
);

Parameters

hrasconn
Identifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file, or ERROR_INVALID_HANDLE.

Remarks

The connection is terminated even if the RasDial call has not yet been completed.

After this call, the hrasconn handle can no longer be used.

An application should not call RasHangUp and then immediately exit. The connection state machine needs time to properly terminate. If the system prematurely terminates the state machine, the state machine may fail to properly close a port, leaving the port in an inconsistent state. A simple way to avoid this problem is to call Sleep(3000) after returning from RasHangUp; after that pause, the application can exit. A more responsive way to avoid the problem is, after returning from RasHangUp, to call RasGetConnectStatus(hrasconn) and Sleep(0) in a loop until RasGetConnectStatus returns ERROR_INVALID_HANDLE.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCONN, RasDial, RasEnumConnections, RasGetConnectStatus, Sleep


RasMonitorDlg

The RasMonitorDlg function displays the Dial-Up Networking Monitor property sheet that describes the status of RAS connections.

BOOL RasMonitorDlg(
  LPTSTR lpszDeviceName,  // pointer to the name of the device to
                          // display initially
  LPRASMONITORDLG lpInfo  // pointer to structure that contains
                          // input and output parameters
);

Parameters

lpszDeviceName
Pointer to a null-terminated string that specifies the name of the device to display initially. If this parameter is NULL, or if the specified device does not exist, the property sheet displays the first device.
lpInfo
Pointer to a RASMONITORDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASMONITORDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user hangs up a connection, the return value is a nonzero value.

If an error occurs, or if the user closes the dialog box without hanging up a connection, the return value is zero. If an error occurs, the dwError member of the RASMONITORDLG structure returns a nonzero system error code or RAS error code.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASMONITORDLG


RasPBDlgFunc

The RasPBDlgFunc function is an application-defined callback function that receives notifications of user activity while the RasPhonebookDlg dialog box is open.

VOID WINAPI RasPBDlgFunc(
  DWORD dwCallbackId,  // an application-defined value
  DWORD dwEvent,       // indicates the event that occurred
  LPTSTR pszText,      // pointer to an additional string argument
  LPVOID pData         // pointer to an additional buffer argument
);

Parameters

dwCallbackId
Indicates the application-defined value that was specified in the dwCallback member of the RASPBDLG structure passed to the RasPhonebookDlg function.
dwEvent
A set of bit flags that indicates the event that occurred. This parameter is one of the following values.
Value | Meaning
RASPBDEVENT_AddEntry | Received when the user creates a new phone-book entry or copies an existing phone-book entry. The pszText parameter is the name of the new or copied entry. The pData parameter is undefined.
RASPBDEVENT_EditEntry | Received when the user changes an existing phone-book entry. The pszText parameter is the name of the modified entry. The pData parameter is undefined.
RASPBDEVENT_RemoveEntry | Received when the user deletes a phone-book entry. The pszText parameter is the name of the deleted entry. The pData parameter is undefined.
RASPBDEVENT_DialEntry | Received when the user successfully dials an entry. The pszText parameter is the name of the newly connected entry. The pData parameter is undefined.
RASPBDEVENT_EditGlobals Received when the user makes changes in the User Preferences property sheet. The pszText parameter is the full path of the default phone-book file selected by the user. The pData parameter is undefined.

This event is also received during dialog startup if the lpszPhonebook parameter of the RasPhonebookDlg call is NULL. In this case, the event informs the caller of the path of the default phone book.
RASPBDEVENT_NoUser | Received during dialog box initialization when the RASPBDFLAG_NoUser flag is set. The pData parameter is a pointer to a RASNOUSER structure. The callback function should fill the structure with the user's logon credentials and dialog timeout. The RasPhonebookDlg function then uses the supplied credentials for authentication by the remote server. The pszText parameter is undefined.
RASPBDEVENT_NoUserEdit | Received if the RASPBDFLAG_NoUser flag is set and the user changes the credentials that you supplied during the RASPBDEVENT_NoUser event. The pData parameter is a pointer to a RASNOUSER structure containing the updated credentials. This occurs during a dialing operation if the user changes his or her password, or if the authentication fails and the user retries authentication with different credentials. The pszText parameter is undefined.

pszText
Pointer to an additional string argument whose meaning depends on the event indicated in the dwEvent parameter.
pData
Pointer to an additional buffer argument whose meaning depends on the event indicated in the dwEvent parameter.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: User-defined.
Unicode: Defined as Unicode and ANSI prototypes.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASNOUSER, RasPhonebookDlg


RasPhonebookDlg

The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. From this modal dialog box, the user can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user preferences. The RasPhonebookDlg function returns when the dialog box closes.

BOOL RasPhonebookDlg(
  LPTSTR lpszPhonebook,  // pointer to the full path and filename of
                         // the phone-book file
  LPTSTR lpszEntry,      // pointer to the name of the phone-book
                         // entry to highlight
  LPRASPBDLG lpInfo      // pointer to a structure that contains
                         // additional parameters
);

Parameters

lpszPhonebook
Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of the phone-book entry to highlight initially. If this parameter is NULL, or if the specified entry does not exist, the dialog box highlights the first entry in the alphabetic list.
lpInfo
Pointer to a RASPBDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASPBDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user selects the Dial button and the function establishes a connection, the return value is a nonzero value.

If an error occurs, or if the user selects the Close button to close the dialog box, the return value is zero. If an error occurs, the dwError member of the RASPBDLG structure returns a nonzero system error code or RAS error code.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASPBDLG


RasRenameEntry

The RasRenameEntry function changes the name of an entry in a phone book.

DWORD RasRenameEntry(
  LPCTSTR lpszPhonebook, // pointer to full path and filename of
                         // phone-book file
  LPCTSTR lpszOldEntry,  // pointer to the old entry name
  LPCTSTR lpszNewEntry   // pointer to the new entry name
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszOldEntry
Pointer to a null-terminated string containing an existing entry name.
lpszNewEntry
Pointer to a null-terminated string containing the new entry name. Before calling RasRenameEntry, call the RasValidateEntryName function to validate the new entry name.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_NAME | The lpszNewEntry name is invalid.
ERROR_ALREADY_EXISTS | An entry with the lpszNewEntry name already exists.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasValidateEntryName


RasSecurityDialogBegin

The RasSecurityDialogBegin function is a third-party RAS security DLL entry point that the Windows NT RAS server calls when a remote user tries to connect. This enables the security DLL to begin its authentication of the remote user.

Note that Windows NT currently provides RAS security host support only for serial devices; other types of connections, such as ISDN or a virtual private network (VPN) connection, are not supported.

DWORD WINAPI RasSecurityDialogBegin(
  HPORT hPort,        // RAS handle to the port
  PBYTE pSendBuf,     // pointer to buffer for sending data
  DWORD SendBufSize,  // size, in bytes, of the send buffer
  PBYTE pRecvBuf,     // pointer to buffer for receiving data
  DWORD RecvBufSize,  // size, in bytes, of the receive buffer
  VOID (WINAPI * RasSecurityDialogComplete)
                      // pointer to the completion function
);

Parameters

hPort
Specifies a RAS port handle. The security DLL uses this handle in other RAS security functions, such as RasSecurityDialogSend and RasSecurityDialogReceive, to identify this authentication transaction.

Note that this handle is valid only in RAS security functions; you cannot use it in other Win32 I/O functions.

pSendBuf
Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogSend function to send text that is displayed in the RAS terminal window on the remote computer.
SendBufSize
Specifies the size, in bytes, of the pSendBuf buffer.
pRecvBuf
Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogReceive function to receive the response from the remote user.
RecvBufSize
Specifies the size, in bytes, of the pRecvBuf buffer.
RasSecurityDialogComplete
Specifies a pointer to a RasSecurityDialogComplete function. When the security DLL has completed the authentication of the remote user, it calls this function to report the results to the RAS server.

Return Values

If the security DLL successfully starts the authentication operation, RasSecurityDialogBegin should return NO_ERROR. In this case, the security DLL must later terminate the authentication transaction by calling the function pointed to by the RasSecurityDialogComplete parameter.

If an error occurs, RasSecurityDialogBegin should return a nonzero error code. In this case, the RAS server hangs up the call and records the error in the Windows NT event log. Returning a nonzero error code terminates the authentication transaction, so the security DLL does not need to call the RasSecurityDialogComplete function.

Remarks

When a Windows NT RAS server receives a call from a remote computer, it calls the RasSecurityDialogBegin function exported by the registered RAS security DLL, if there is one. When the RAS server calls this function, it passes the following information to the security DLL:

  • A port handle to identify the connection
  • Pointers to buffers to use when communicating with the remote user
  • A pointer to a RasSecurityDialogComplete function to call when the authentication has been completed

The port handle and buffer pointers are valid until you call RasSecurityDialogComplete to terminate the authentication transaction.

Your RasSecurityDialogBegin implementation must return as soon as possible, because the RAS server is blocked and cannot accept any other calls until RasSecurityDialogBegin returns. The RasSecurityDialogBegin function should copy the input parameters and create a thread to communicate with and authenticate the remote user.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasSecurityDialogComplete, RasSecurityDialogReceive, RasSecurityDialogSend


RasSecurityDialogComplete

The RasSecurityDialogComplete function notifies the RAS server of the results of a third-party security authentication transaction. A third-party RAS security DLL calls RasSecurityDialogComplete when it has completed its authentication of the remote user.

The RAS server passes a pointer to the RasSecurityDialogComplete function when the server calls the RasSecurityDialogBegin entry point of the security DLL.

VOID RasSecurityDialogComplete(
  SECURITY_MESSAGE *pSecMsg  // pointer to the security message
                             // structure
);

Parameters

pSecMsg
Pointer to a SECURITY_MESSAGE structure that contains the results of the authentication transaction.

Return Values

None.

Remarks

When a security DLL has finished authenticating the remote user, it calls the RasSecurityDialogComplete function to report the results. The RAS server then performs a cleanup sequence. As part of this cleanup sequence, the RAS server calls the security DLL's RasSecurityDialogEnd function to give the DLL an opportunity to perform its own cleanup, if necessary.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasSecurityDialogBegin, RasSecurityDialogComplete, RasSecurityDialogEnd, SECURITY_MESSAGE


RasSecurityDialogEnd

The RasSecurityDialogEnd function is a third-party RAS security DLL entry point that the Windows NT RAS server calls to terminate an authentication transaction.

DWORD WINAPI RasSecurityDialogEnd(
  HPORT hPort  // RAS handle to the port
);

Parameters

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.

Return Values

If the security DLL returns NO_ERROR, the RAS server does not terminate the authentication transaction. In this case, the security DLL must later call the RasSecurityDialogComplete function when it is ready to terminate.

If the security DLL returns a nonzero error code, the RAS server terminates the authentication transaction. In this case, the security DLL does not need to make another RasSecurityDialogComplete call. You should return an error code defined in WINERROR.H or RASERROR.H, such as ERROR_PORT_DISCONNECTED.

Remarks

When a security DLL has finished authenticating the remote user, it calls the RasSecurityDialogComplete function. The RAS server then performs a cleanup sequence that includes a call to the DLL's RasSecurityDialogEnd function. This gives the security DLL an opportunity to perform any necessary cleanup. To terminate the authentication transaction, RasSecurityDialogEnd must return a nonzero error code.

The RAS server may also call RasSecurityDialogEnd if it needs to abnormally terminate the authentication transaction before the security DLL calls RasSecurityDialogComplete. In this case, the security DLL should terminate the worker thread associated with the hPort port handle, and perform any other necessary cleanup. If RasSecurityDialogEnd returns a nonzero value, the security DLL does not need to call RasSecurityDialogComplete.

For either a normal or abnormal termination, your RasSecurityDialogEnd function can return NO_ERROR to delay the termination. If it does so, it must later call RasSecurityDialogComplete when it is ready to terminate.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasSecurityDialogBegin, RasSecurityDialogComplete


RasSecurityDialogGetInfo

The RasSecurityDialogGetInfo function is called by a RAS security DLL to get information about a port from the RAS server.

To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. Then call the GetProcAddress function to get the DLL's RasSecurityDialogGetInfo entry point.

DWORD RasSecurityDialogGetInfo(
  HPORT hPort,  // RAS handle to port
  RAS_SECURITY_INFO *pBuffer
                // pointer to structure that gets port information
);

Parameters

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
Pointer to a RAS_SECURITY_INFO structure that receives information about the specified RAS port.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the error codes defined in RASERROR.H or WINERROR.H. GetLastError does not provide extended error information.

Remarks

The RasSecurityDialogGetInfo function retrieves information about the port associated with a RAS security DLL authentication transaction.

The LastError member of the RAS_SECURITY_INFO structure indicates the state of the last RasSecurityDialogReceive call for the port. If the receive operation has been completed successfully, LastError is SUCCESS and the BytesReceived member indicates the number of bytes received. Otherwise, LastError is PENDING if the receive operation is still in progress, or a nonzero error code if the receive operation failed.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.
Import Library: Included as a resource in rasman.dll.

See Also

Remote Access Service Overview, RAS Server Administration Functions, GetProcAddress, LoadLibrary, RAS_SECURITY_INFO, RasSecurityDialogReceive


RasSecurityDialogReceive

The RasSecurityDialogReceive function starts an asynchronous operation that receives a remote user's response to a security challenge. The response is the input that the user typed in a terminal window on the remote computer. A third-party RAS security DLL calls this function as part of its authentication of the remote user.

To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. Then call the GetProcAddress function to get the DLL's RasSecurityDialogReceive entry point.

DWORD WINAPI RasSecurityDialogReceive(
  HPORT hPort,   // RAS handle to the port
  PBYTE pBuffer, // pointer to buffer that receives the user's
                 // response
  PWORD pBufferLength,
                 // returns size, in bytes, of the data received
  DWORD Timeout, // time-out period, in seconds
  HANDLE hEvent  // event that is signaled when operation is finished
);

Parameters

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
Pointer to the receive buffer that was passed to the security DLL in the RasSecurityDialogBegin call. When the asynchronous receive operation has been completed successfully, this buffer contains the response from the remote user.
pBufferLength
Pointer to a WORD variable. On input, this variable must specify the size, in bytes, of the pBuffer buffer. When the receive operation has been completed, the variable indicates the number of bytes returned in the pBuffer buffer.
Timeout
Specifies a time-out period, in seconds, after which the RAS server sets the hEvent event object to the signaled state.

If this value is zero, there is no time-out period; that is, the RAS server does not signal the event object until the receive operation has been completed.

hEvent
Specifies the handle of an event object created by the CreateEvent function. The RAS server sets the event object to the signaled state when the receive operation has been completed or when the time-out period has elapsed.

Return Values

If the function is successful, the return value is PENDING (defined in RASERROR.H). This indicates that the receive operation is in progress.

If an error occurs, the return value is one of the error codes defined in RASERROR.H or WINERROR.H. GetLastError does not provide extended error information.

Remarks

After calling the RasSecurityDialogSend function to send a security challenge to the remote user, the security DLL must call the RasSecurityDialogReceive function to get the user's response.

The RasSecurityDialogReceive function is asynchronous. When the function returns, the security DLL must use one of the wait functions, such as WaitForSingleObject, to wait for the hEvent event object to be signaled. The RAS server signals the event object when the receive operation has been completed or when the time-out interval has elapsed. If the receive operation is successful, the pBuffer buffer contains the response from the remote user, and the pBufferLength parameter indicates the number of bytes received. If the remote user sends more bytes than will fit in the buffer, the RAS server buffers the excess bytes and returns them in the next RasSecurityDialogReceive call.

You can use the Timeout parameter to specify a time-out interval. If the time-out elapses, the RAS server signals the event object, and the pBufferLength parameter indicates that zero bytes were transferred. Alternatively, you can set Timeout to zero, and specify a time-out interval in the wait function that you use to wait for the event object to be signaled.

When a security DLL is authenticating a remote user, the connection operation on the remote computer enters a RASCS_Interactive paused state. The message sent by RasSecurityDialogSend is displayed as output in a terminal window on the remote computer. The response received by RasSecurityDialogReceive is the input that the remote user types in the terminal window. The RASCS_Interactive value is defined in the RASCONNSTATE enumeration.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.
Import Library: Included as a resource in rasman.dll.

See Also

Remote Access Service Overview, RAS Server Administration Functions, CreateEvent, GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogSend, WaitForSingleObject


RasSecurityDialogSend

The RasSecurityDialogSend function sends a message to be displayed in a terminal window on a remote computer. A third-party RAS security DLL sends this message as part of its authentication of a remote user.

To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. Then call the GetProcAddress function to get the DLL's RasSecurityDialogSend entry point.

DWORD RasSecurityDialogSend(
  HPORT hPort,       // RAS handle to the port
  PBYTE pBuffer,     // pointer to buffer containing data to send
  WORD BufferLength  // size, in bytes, of the data being sent
);

Parameters

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
Pointer to the send buffer that was passed to the security DLL in the call to RasSecurityDialogBegin. Before calling RasSecurityDialogSend, copy into this buffer the message to send to the remote user. The SendBufSize parameter of the RasSecurityDialogBegin function indicates the maximum number of bytes you can copy to this buffer.
BufferLength
Specifies the number of bytes to send in the pBuffer buffer.

Return Values

If the function is successful, the return value is PENDING (defined in RASERROR.H). This indicates that the send operation is in progress.

If an error occurs, the return value is one of the error codes defined in RASERROR.H or WINERROR.H. GetLastError does not provide extended error information.

Remarks

The RasSecurityDialogSend function is asynchronous. After calling it to send a message to the remote user, call the RasSecurityDialogReceive function, and then wait for a response. The security DLL can make any number of RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive call.

When a security DLL is authenticating a remote user, the connection operation on the remote computer enters a RASCS_Interactive paused state. The message sent by RasSecurityDialogSend is displayed as output in a terminal window on the remote computer. The response received by RasSecurityDialogReceive is the input that the remote user types in the terminal window. The RASCS_Interactive value is defined in the RASCONNSTATE enumeration.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.
Import Library: Included as a resource in rasman.dll.

See Also

Remote Access Service Overview, RAS Server Administration Functions, GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogBegin, RasSecurityDialogReceive


RasSetAutodialAddress

The RasSetAutodialAddress function can add an address to the AutoDial mapping database. Alternatively, the function can delete or modify the data associated with an existing address in the database.

DWORD RasSetAutodialAddress(
  LPCTSTR lpszAddress,        // pointer to a network address string
  DWORD dwReserved,           // reserved; must be zero
  LPRASAUTODIALENTRY lpAutoDialEntries,
                              // pointer to buffer containing
                              // AutoDial entry data
  DWORD dwcbAutoDialEntries,  // size, in bytes, of the buffer
  DWORD dwcAutoDialEntries    // number of entries in the buffer
);

Parameters

lpszAddress
Pointer to a null-terminated string that specifies the address to add, delete, or modify. This can be an IP address ("127.95.1.4"), Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").
dwReserved
Reserved; must be zero.
lpAutoDialEntries
Pointer to an array of one or more RASAUTODIALENTRY structures to be associated with the lpszAddress address. If lpAutoDialEntries is NULL and dwcbAutodialEntries is zero, RasSetAutodialAddress deletes all structures associated with lpszAddress from the mapping database.
dwcbAutoDialEntries
Specifies the size, in bytes, of the lpAutodialEntries buffer.
dwcAutoDialEntries
Specifies the number of RASAUTODIALENTRY structures in the lpAutoDialEntries buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_SIZE | The dwSize member of the RASAUTODIALENTRY structure is an invalid value.
ERROR_INVALID_PARAMETER | The lpszAddress parameter was NULL.

Remarks

An address in the AutoDial mapping database can have any number of associated RASAUTODIALENTRY entries. Each entry specifies AutoDial information for a particular TAPI dialing location.

If the address specified by the lpszAddress parameter is an existing address in the database and the lpAutoDialEntries parameter is not NULL, the RasSetAutodialAddress function modifies the set of AutoDial entries associated with the address. If an entry in the lpAutoDialEntries array specifies a dialing location for which the address already has an entry, the function replaces the existing entry with the new entry. Otherwise, the function simply adds the lpAutoDialEntries entries to the set of entries for the address.

If the lpszAddress address exists in the database and lpAutoDialEntries is NULL and dwcbAutodialEntries is zero, RasSetAutodialAddress deletes the address from the database.

If the lpszAddress address does not exist in the database, RasSetAutodialAddress adds the address to the database. The lpAutoDialEntries parameter specifies the AutoDial entries to associate with the new address.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASAUTODIALENTRY, RasEnumAutodialAddresses, RasGetAutodialAddress


RasSetAutodialEnable

The RasSetAutodialEnable function sets whether the AutoDial feature is enabled for a specified TAPI dialing location. For more information about TAPI dialing locations, see the Win32 Telephony (TAPI) Programmer's Reference.

DWORD RasSetAutodialEnable(
  DWORD dwDialingLocation,
                 // identifier of the TAPI dialing location
  BOOL fEnabled  // AutoDial state for this location
);

Parameters

dwDialingLocation
Specifies the identifier of a TAPI dialing location.
fEnabled
Specify TRUE to enable AutoDial for the specified dialing location, or FALSE to disable it.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasGetAutodialEnable


RasSetAutodialParam

The RasSetAutodialParam function sets the value of an AutoDial parameter.

DWORD RasSetAutodialParam(
  DWORD dwKey,     // indicates the parameter to set
  LPVOID lpvValue, // pointer to a buffer that specifies the value
  DWORD dwcbValue  // size, in bytes, of the buffer
);

Parameters

dwKey
Indicates the AutoDial parameter to set. This parameter can be one of the following values.
Value | Meaning
RASADP_DisableConnectionQuery | The lpvValue parameter points to a DWORD value. If this value is zero (the default), AutoDial displays a dialog box to query the user before creating a connection. If this value is 1, and the AutoDial database has the phone-book entry to dial, AutoDial creates a connection without displaying the dialog box.
RASADP_LoginSessionDisable | The lpvValue parameter points to a DWORD value. If this value is 1, the system disables all AutoDial connections for the current logon session. If this value is zero (the default), AutoDial connections are enabled. The AutoDial system service changes this value to zero when a new user logs on to the workstation.
RASADP_SavedAddressesLimit | The lpvValue parameter points to a DWORD value that indicates the maximum number of addresses that AutoDial stores in the registry. AutoDial first stores addresses that it used to create an AutoDial connection; then it stores addresses that it learned after a RAS connection was created. Addresses written using the RasSetAutodialAddress function are always saved, and are not included in calculating the limit. The default value is 100.
RASADP_FailedConnectionTimeout | The lpvValue parameter points to a DWORD value that indicates a timeout value, in seconds. When an AutoDial connection attempt fails, the AutoDial system service disables subsequent attempts to reach the same address for the timeout period. This prevents AutoDial from displaying multiple connection dialog boxes for the same logical request by an application. The default value is 5.
RASADP_ConnectionQueryTimeout | The lpvValue parameter points to a DWORD value that indicates a timeout value, in seconds. Before attempting an AutoDial connection, the system will display a dialog asking the user to confirm that the system should dial. The dialog has a countdown timer that will terminate the dialog with a "Do not dial" selection if the user takes no action. The DWORD value pointed to by lpvValue specifies the initial time on this countdown timer.

lpvValue
Pointer to a buffer that contains the new value for the specified parameter.
dwcbValue
Specifies the size, in bytes, of the value in the lpvValue buffer.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_INVALID_PARAMETER | The dwKey or lpvValue parameter is invalid.
ERROR_INVALID_SIZE | The size specified by the dwcbValue is invalid.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasGetAutodialParam, RasSetAutodialAddress


RasSetCredentials

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry.

DWORD RasSetCredentials(
  LPCTSTR lpszPhonebook,   // pointer to the full path and filename
                           // of a phone-book file
  LPCTSTR lpszEntry,       // pointer to the name of a phone-book
                           // entry
  LPRASCREDENTIALS lpCredentials,
                           // pointer to structure that specifies the
                           // credentials
  BOOL fClearCredentials   // if true, credentials are cleared
                           // if false, credentials are set
);

Parameters

lpszPhonebook
Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of a phone-book entry.
lpCredentials
Pointer to a RASCREDENTIALS structure that specifies the user credentials to set for the specified phone-book entry. Before calling RasSetCredentials, set the dwSize member of the structure to sizeof(RASCREDENTIALS). Set the dwMask member to indicate the credential information to be set.
fClearCredentials
Flag that indicates whether RasSetCredentials clears existing credentials by setting them to the empty string, "". If this flag is TRUE, the dwMask member of the RASCREDENTIALS structure indicates the credentials that the function sets to the empty string. If this flag is FALSE, the function sets the indicated credentials according to the contents of their corresponding RASCREDENTIALS members.

Return Values

If the function succeeds the return value is zero.

If the function fails, the return value can be one of the following error codes:

Value | Meaning
ERROR_CANNOT_OPEN_PHONEBOOK | The specified phone book cannot be found.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The specified entry does not exist in the phone book.
ERROR_INVALID_PARAMETER | The lpCredentials parameter was NULL.
ERROR_INVALID_SIZE | The dwSize member of the RASCREDENTIALS structure is an unrecognized value.

Remarks

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry. The credentials stored with a phone-book entry are the credentials of the last user to successfully connect using the specified phone-book entry, or the credentials subsequently specified in a call to the RasSetCredentials or RasSetEntryDialParams function for the phone-book entry.

The RasSetCredentials function is the preferred way of securely storing credentials with a phone-book entry. RasSetCredentials supersedes the RasSetEntryDialParams function, which may not be supported in future releases of Windows NT.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASCREDENTIALS, RasGetCredentials, RasSetEntryDialParams


RasSetEntryDialParams

The RasSetEntryDialParams function changes the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phonebook entry.

DWORD RasSetEntryDialParams(
  LPCTSTR lpszPhonebook, // pointer to the full path and filename of
                         // the phonebook file
  LPRASDIALPARAMS lprasdialparams,
                         // pointer to a structure with the new
                         // connection parameters
  BOOL fRemovePassword   // indicates whether to remove password
                         // from entry's parameters
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

lprasdialparams
Points to a RASDIALPARAMS structure containing the connection parameters to be associated with the phonebook entry. RasSetEntryDialParams uses the structure's members as follows:
Member | Description
dwSize | Must specify the sizeof(RASDIALPARAMS) to identify the version of the structure.
szEntryName | A null-terminated string that identifies the phonebook entry to set parameters for.
szPhoneNumber | Not used. Set to NULL.
szCallbackNumber | A null-terminated string containing the callback phone number. If szCallbackNumber is an empty string ( "" ), the callback number is not changed.
szUserName | A null-terminated string containing the logon name of the user associated with this entry. If szUserName is an empty string, the user name is not changed.
szPassword | A null-terminated string containing the password for the user specified by szUserName. If szUserName is an empty string, the password is not changed. If szPassword is an empty string and fRemovePassword is FALSE, the password is set to the empty string. If fRemovePassword is TRUE, the password stored in this phonebook entry for the user specified by szUserName is removed regardless of the contents of the szPassword string.
szDomain | A null-terminated string containing the name of the domain to log on to. If szDomain is an empty string, the domain name is not changed.

fRemovePassword
Indicates whether to remove the phonebook entry's stored password for the user specified by lprasdialparams->szUserName. If fRemovePassword is TRUE, the password is removed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes:

Value | Description
ERROR_BUFFER_INVALID
 | The address or buffer specified by lprasdialparams is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK
 | The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
 | The phonebook entry does not exist.

Remarks

Windows CE: The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasGetEntryDialParams


RasSetEntryProperties

The RasSetEntryProperties function changes the connection information for an entry in the phone book or creates a new phone-book entry.

DWORD RasSetEntryProperties(
  LPCTSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPCTSTR lpszEntry,      // pointer to an entry name
  LPRASENTRY lpRasEntry,  // buffer that contains entry information
  DWORD dwEntryInfoSize,  // size, in bytes, of the lpRasEntry
                          // buffer
  LPBYTE lpbDeviceInfo,   // buffer that contains device-specific
                          // configuration information
  DWORD dwDeviceInfoSize  // size, in bytes, of the lpbDeviceInfo
                          // buffer
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing an entry name.

If the entry name matches an existing entry, RasSetEntryProperties modifies the properties of that entry.

If the entry name does not match an existing entry, RasSetEntryProperties creates a new phone-book entry. For new entries, call the RasValidateEntryName function to validate the entry name before calling RasSetEntryProperties.

lpRasEntry
Pointer to a RASENTRY structure that contains the new connection data to be associated with the phone-book entry specified by the lpszEntry parameter.

The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASENTRY structure contains the offset to the first string.

dwEntryInfoSize
Specifies the size, in bytes, of the buffer specified by the lpRasEntry parameter.
lpbDeviceInfo
Pointer to a buffer containing device-specific configuration information. This is opaque TAPI device configuration information. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer's Reference.

Windows NT: This parameter is unused. The calling function should set this parameter to NULL.

dwDeviceInfoSize
Specifies the size, in bytes, of the lpbDeviceInfo buffer.

Windows NT: This parameter is unused. The calling function should set this parameter to zero.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.

Remarks

Windows CE: For Windows CE version 1.0, the lpbDeviceInfo and lpdwDeviceInfoSize parameters are ignored and should be set to NULL. To set device specific configuration information use the RasSetEntryDevConfig function.

For Windows CE version 2.0 and later, device configuration information can be set by using lpbDeviceInfo and lpdwDeviceInfoSize parameters.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RASENTRY, RasCreatePhonebookEntry, RasGetEntryProperties, RasValidateEntryName


RasSetSubEntryProperties

The RasSetSubEntryProperties function creates a new subentry or modifies an existing subentry of a specified phone-book entry.

DWORD RasSetSubEntryProperties(
  LPCTSTR lpszPhonebook,    // pointer to full path and filename of
                            // the phone-book file
  LPCTSTR lpszEntry,        // pointer to an entry name
  DWORD dwSubEntry,         // index of the subentry
  LPRASSUBENTRY lpRasSubEntry,
                            // pointer to structure containing
                            // information about subentry
  DWORD dwcbRasSubEntry     // size, in bytes, of the structure
  LPBYTE lpbDeviceConfig,   // pointer to TAPI device configuration
  DWORD dwcbDeviceConfig    // size of TAPI device configuration
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing the name of an existing entry in the phone book.
dwSubEntry
Specifies the one-based index of the subentry. If the index matches an existing subentry index, the function changes the properties of that subentry. If the index does not match an existing index, the function creates a new subentry.
lpRasSubEntry
Pointer to a RASSUBENTRY structure that contains the data for the subentry.

The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASSUBENTRY structure contains the offset to the first string.

dwcbRasSubEntry
Specifies the size, in bytes, of the lpRasSubEntry buffer.
lpbDeviceConfig
Pointer to a TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter. For more information about TAPI device configuration blocks, see the function lineGetDevConfig.
dwcbDeviceConfig
Specifies the size of the TAPI device configuration block. This parameter is currently unused. The caller should pass zero for this parameter.

Return Values

If the function succeeds, the return value is zero.

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

Value | Meaning
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.

Remarks

A RAS phone-book entry can have zero or more subentries, each minimally consisting of a device and a phone number. A phone-book entry with multiple subentries can be configured to dial either the first available subentry or all subentries when the entry is dialed.

Use the RasGetEntryProperties function to retrieve a RASENTRY structure containing information about the subentries of a phone-book entry. The dwSubEntries member indicates the number of subentries and the dwDialMode member indicates the dialing configuration.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasGetEntryProperties, RASENTRY, RASSUBENTRY


RasValidateEntryName

The RasValidateEntryName function validates the format of a connection entry name. The name must contain at least one non-white-space alphanumeric character.

DWORD RasValidateEntryName(
  LPCTSTR lpszPhonebook,  // pointer to full path and filename of
                          // phone-book file
  LPCTSTR lpszEntry       // pointer to the entry name to validate
);

Parameters

lpszPhonebook
Windows NT: Pointer to a null-terminated string that specifies the full path and filename of a phone-book (.PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string containing an entry name.

Windows NT: The entry name cannot begin with a period (".").

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is ERROR_INVALID_NAME or ERROR_ALREADY_EXISTS.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Import Library: Use rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Functions, RasCreatePhonebookEntry, RasGetEntryProperties


Remote Access Service Structures

Use the following structures to implement Remote Access Service functionality.

RASADPARAMS
RASAMB
RASAUTODIALENTRY
RASCONN
RASCONNSTATUS
RASCREDENTIALS
RASCTRYINFO
RASDEVINFO
RASDIALDLG
RASDIALEXTENSIONS
RASDIALPARAMS
RASENTRY
RASENTRYDLG
RASENTRYNAME
RASIPADDR
RASMONITORDLG
RASNOUSER
RASPBDLG
RASPPPIP
RASPPPIPX
RASPPPNBF
RASSLIP
RASSUBENTRY


RAS Server Administration Structures

For Windows NT version 4.0, use the following structures to implement RAS Server Administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMETERS
RAS_PORT_0
RAS_PORT_1
RAS_PORT_STATISTICS
RAS_PPP_ATCP_RESULT
RAS_PPP_IPCP_RESULT
RAS_PPP_IPXCP_RESULT
RAS_PPP_NBFCP_RESULT
RAS_PPP_PROJECTION_RESULT
RAS_SECURITY_INFO
RAS_SERVER_0
RAS_USER_0
SECURITY_MESSAGE


RAS Server Administration Union

For Windows NT version 4.0, use the following union to implement RAS Server Administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMS_VALUE


RAS_PARAMETERS

The RAS_PARAMETERS structure is used by the RasAdminPortGetInfo function to return the name and value of a media-specific parameter associated with a port on a Windows NT RAS Server.

struct RAS_PARAMETERS {
    CHAR  P_Key    [RASSAPI_MAX_PARAM_KEY_SIZE];
    RAS_PARAMS_FORMAT  P_Type;
    BYTE  P_Attributes;
    RAS_PARAMS_VALUE  P_Value;
};

Members

P_Key
Specifies the name of the key that represents the media-specific parameter, such as MAXCONNECTBPS.
P_Type
Identifies the type of data associated with the parameter. This member can be one of the following values from the RAS_PARAMS_FORMAT enumeration.
Value | Meaning
ParamNumber | Indicates that the data associated with the key is a number.
ParamString | Indicates that the data associated with the key is a string.

P_Attributes
Reserved.
P_Value
Specifies the value associated with the parameter. This member is a RAS_PARAMS_VALUE union. If the P_Type member is ParamNumber, the Number member of the union contains the value. If P_Type is ParamString, the String member of the union contains the value.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PARAMS_VALUE

The RAS_PARAMS_VALUE union is used in the RAS_PARAMETERS structure to store the data associated with a media-specific parameter. The P_Type member of the RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT enumeration to indicate the type of value currently stored in RAS_PARAMS_VALUE.

union RAS_PARAMS_VALUE {
    DWORD  Number;
    struct    {
        DWORD  Length ;
        PCHAR  Data ;
    } String;
};

Members

Number
If the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the Number member contains the value of the media-specific parameter. For example, the MAXCONNECTBPS parameter is of type ParamNumber, and the value might be 19200.

If the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the Number member contains the value of the media-specific parameter. For example, the MAXCONNECTBPS parameter is of type ParamNumber, and the value might be 19200.

String
If the P_Type member of the RAS_PARAMETERS structure is ParamString, the String member contains the value of the media-specific parameter.
Length
Specifies the length, in characters, of the string pointed to by the Data member.
Data
Pointer to a buffer that contains the string value of a media-specific parameter.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PARAMETERS, RAS_PARAMS_FORMAT


RAS_PORT_0

[This is preliminary documentation and subject to change.]

The RAS_PORT_0 structure contains information that describes a RAS port.

typedef struct _RAS_PORT_0 {
    WCHAR wszPortName[RASSAPI_MAX_PORT_NAME];
    WCHAR wszDeviceType[RASSAPI_MAX_DEVICETYPE_NAME];
    WCHAR wszDeviceName[RASSAPI_MAX_DEVICE_NAME];
    WCHAR wszMediaName[RASSAPI_MAX_MEDIA_NAME];
    DWORD reserved;
    DWORD Flags;
    WCHAR wszUserName[UNLEN + 1];
    WCHAR wszComputer[NETBIOS_NAME_LEN];
    DWORD dwStartSessionTime;
    WCHAR wszLogonDomain[DNLEN + 1];
    BOOL fAdvancedServer;
} RAS_PORT_0, *PRAS_PORT_0;

Members

wszPortName
A null-terminated Unicode string that specifies the name of the port, such as "COM1".
wszDeviceType
A null-terminated Unicode string that specifies the type of the device on which the connection was made, such as "Modem" or "ISDN". The list of device types that might be specified in this member includes all the device types installed on the server, including third-party devices.
wszDeviceName
A null-terminated Unicode string that specifies the name of the device on which the connection was made, such as "Hayes 9600" or "PCIMACISDN1".
wszMediaName
A null-terminated Unicode string that specifies the name of the media used for the connection, such as "rasser" or "rastapi".
reserved
This member is reserved.
Flags
A set of bit flags that specify the nature of the connection made on this port. This member can be a combination of the following flags.
Value | Meaning
GATEWAY_ACTIVE | If this flag is set, the NetBIOS gateway is active on the server.
MESSENGER_PRESENT | If this flag is set, the Windows NT messenger service is running on the remote client.
PORT_MULTILINKED If this flag is set, the port is multilinked with other ports. You can use this information for displaying the connection status as a multilinked port.

For a multilinked port, the RAS_PORT_STATISTICS structure contains two sets of statistics: one for the port alone, and another for the combined ports in the multilink connection.
PPP_CLIENT | If this flag is set, the remote client connected using PPP. If this flag is not set, the remote client connected using the AMB protocol.
REMOTE_LISTEN | If this flag is set, the RemoteListen parameter of the NetBIOS gateway is set to 1 on the server.
USER_AUTHENTICATED | If this flag is set, a remote client is connected to the server and the user has been authenticated. You can check this flag to ensure that a client is actually connected to a port.

If the MESSENGER_PRESENT, GATEWAY_ACTIVE, and REMOTE_LISTEN flags are set, you can use the Windows NT messenger service to send an administrative message to the remote client. If MESSENGER_PRESENT and REMOTE_LISTEN are set, but GATEWAY_ACTIVE is not, you can send a message to the client only if you send the message from the RAS server the client is dialed in to.

If the MESSENGER_PRESENT, GATEWAY_ACTIVE, and REMOTE_LISTEN flags are set, you can use the Windows NT messenger service to send an administrative message to the remote client. If MESSENGER_PRESENT and REMOTE_LISTEN are set, but GATEWAY_ACTIVE is not, you can send a message to the client only if you send the message from the RAS server the client is dialed in to.

wszUserName
A null-terminated Unicode string that specifies the name of the remote user connected to this port.
wszComputer
A null-terminated Unicode string that specifies the name of the remote client computer.
dwStartSessionTime
Specifies the time, in seconds from January 1, 1970, that the client connected to the RAS server on this port. You can use the standard Win32 time routines to format this value for display.
wszLogonDomain
A null-terminated Unicode string that specifies the name of the Windows NT domain on which the remote user was authenticated. This string is the domain name only, with no "\\" prefix.
fAdvancedServer
A flag that is nonzero if the RAS server associated with this port is a Windows NT Advanced Server. You can use this information to determine the name of the server that has the user account database. If the RAS server is an Advanced Server, you can get the name of the user account server by concatenating the prefix "\\" to the name returned in the wszLogonDomain member. This is because for an Advanced Server the local logon domain name is the same as the server name. If the RAS server is a Windows NT Workstation, you can use the RasAdminGetUserAccountServer function to get the name of the user account server.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminGetUserAccountServer, RasAdminPortEnum


RAS_PORT_1

[This is preliminary documentation and subject to change.]

The RAS_PORT_1 structure contains information about a RAS port.

typedef struct _RAS_PORT_1 {
    RAS_PORT_0  rasport0;
    DWORD       LineCondition;
    DWORD       HardwareCondition;
    DWORD       LineSpeed;
    WORD        NumStatistics;
    WORD        NumMediaParms;
    DWORD       SizeMediaParms;
    RAS_PPP_PROJECTION_RESULT  ProjResult;
} RAS_PORT_1, *PRAS_PORT_1;

Members

rasPort0
A RAS_PORT_0 structure that contains information about the port, such as the name of the port, the name of the remote user connected to the port, and so on.
LineCondition
Specifies the state of the port. This member can be one of the following values.
Value | Meaning
RAS_PORT_NON_OPERATIONAL | The port is not operational. Check the event log for errors reported by the server.
RAS_PORT_DISCONNECTED | The port is currently disconnected.
RAS_PORT_CALLING_BACK | The RAS server is calling back the RAS client.
RAS_PORT_LISTENING | The port is waiting for a client to call in.
RAS_PORT_AUTHENTICATING | The server is in the process of authenticating the remote client.
RAS_PORT_AUTHENTICATED | The remote client is now authenticated.
RAS_PORT_INITIALIZING | The device attached to the port is being initialized. The state of the port will change to RAS_PORT_LISTENING when the initialization has been completed.

HardwareCondition
Specifies one of the following values to indicate the state of the device attached to the port.
Value | Meaning
RAS_MODEM_OPERATIONAL | The modem attached to this port is operational and is ready to receive client calls.
RAS_MODEM_HARDWARE_FAILURE | The modem attached to this port has a hardware problem.

LineSpeed
Specifies the speed, in bits per second, with which the computer can communicate with the port.
NumStatistics
This member is not used. The RAS administration functions, such as the RasAdminPortGetInfo function, use the RAS_PORT_STATISTICS structure to return port statistics.
NumMediaParms
Specifies the number of media-specific parameters for this port. For serial media this is typically the number of values that appear in the SERIAL.INI file.
SizeMediaParms
Specifies the size, in bytes, of the buffer required for all media-specific parameters. The RasAdminPortGetInfo function returns a buffer containing an array of RAS_PARAMETERS structures with the media parameters and values for the port.
ProjResult
A RAS_PPP_PROJECTION_RESULT structure that specifies the PPP projection information for this port. This structure provides information for each protocol that is negotiated when a RAS client connects to a server.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PARAMETERS, RAS_PORT_0, RAS_PORT_STATISTICS, RAS_PPP_PROJECTION_RESULT, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PORT_STATISTICS

The RAS_PORT_STATISTICS structure reports the statistics that a RAS server collects for a connected port. The RAS server resets the various statistic counters each time the port is connected. You can call the RasAdminPortClearStatistics function to force the RAS server to reset the statistic counters.

For a port that is part of a multilink connection, this structure provides two sets of statistics. The first set contains the cumulative statistics for all ports in the connection. These statistics are the same for all ports in the connection. The second set contains the statistics for just this port. If the port is not part of a multilink connection, both sets of statistics have the same information. To determine whether a port is part of a multilink connection, check the PORT_MULTILINKED bit in the Flags member of the port's RAS_PORT_0 structure.

typedef struct _RAS_PORT_STATISTICS
{
    // The connection statistics are followed by port statistics
    // A connection is across multiple ports.
    DWORD   dwBytesXmited;
    DWORD   dwBytesRcved;
    DWORD   dwFramesXmited;
    DWORD   dwFramesRcved;
    DWORD   dwCrcErr;
    DWORD   dwTimeoutErr;
    DWORD   dwAlignmentErr;
    DWORD   dwHardwareOverrunErr;
    DWORD   dwFramingErr;
    DWORD   dwBufferOverrunErr;
    DWORD   dwBytesXmitedUncompressed;
    DWORD   dwBytesRcvedUncompressed;
    DWORD   dwBytesXmitedCompressed;
    DWORD   dwBytesRcvedCompressed;

    // the following are the port statistics
    DWORD   dwPortBytesXmited;
    DWORD   dwPortBytesRcved;
    DWORD   dwPortFramesXmited;
    DWORD   dwPortFramesRcved;
    DWORD   dwPortCrcErr;
    DWORD   dwPortTimeoutErr;
    DWORD   dwPortAlignmentErr;
    DWORD   dwPortHardwareOverrunErr;
    DWORD   dwPortFramingErr;
    DWORD   dwPortBufferOverrunErr;
    DWORD   dwPortBytesXmitedUncompressed;
    DWORD   dwPortBytesRcvedUncompressed;
    DWORD   dwPortBytesXmitedCompressed;
    DWORD   dwPortBytesRcvedCompressed;

} RAS_PORT_STATISTICS, *PRAS_PORT_STATISTICS;

Members

dwBytesXmited
Specifies the total number of bytes transmitted by the connection.
dwBytesRcved
Specifies the total number of bytes received by the connection.
dwFramesXmited
Specifies the total number of frames transmitted by the connection.
dwFramesRcved
Specifies the total number of frames received by the connection.
dwCrcErr
Specifies the total number of CRC errors on the connection. CRC errors are caused by the failure of a cyclic redundancy check. A CRC error indicates that one or more characters in the data packet received were found garbled on arrival.
dwTimeoutErr
Specifies the total number of time-out errors on the connection. Time-out errors occur when an expected character is not received in time. When this occurs, the software assumes that the data has been lost and requests that it be resent.
dwAlignmentErr
Specifies the total number of alignment errors on the connection. Alignment errors occur when a character received is not the one expected. This usually happens when a character is lost or when a time-out error occurs.
dwHardwareOverrunErr
Specifies the total number of hardware overrun errors on the connection. These errors indicate the number of times the sending computer has transmitted characters faster than the receiving computer hardware can process them. If this problem persists, reduce the BPS connection rate on the client.
dwFramingErr
Specifies the total number of framing errors on the connection. A framing error occurs when an asynchronous character is received with an invalid start or stop bit.
dwBufferOverrunErr
Specifies the total number of buffer overrun errors on the connection. A buffer overrun error occurs when the sending computer is transmitting characters faster than the receiving computer can accommodate them. If this problem persists, reduce the BPS connection rate on the client.
dwBytesXmitedUncompressed
Specifies the total number of bytes transmitted uncompressed by the connection.
dwBytesRcvedUncompressed
Specifies the total number of bytes received uncompressed by the connection.
dwBytesXmitedCompressed
Specifies the total number of bytes transmitted compressed by the connection.
dwBytesRcvedCompressed
Specifies the total number of bytes received compressed by the connection.
dwPortBytesXmited
Specifies the total number of bytes transmitted by the port.
dwPortBytesRcved
Specifies the total number of bytes received by the port.
dwPortFramesXmited
Specifies the total number of frames transmitted by the port.
dwPortFramesRcved
Specifies the total number of frames received by the port.
dwPortCrcErr
Specifies the total number of CRC errors on the port. CRC errors are caused by the failure of a cyclic redundancy check. A CRC error indicates that one or more characters in the data packet received were found garbled on arrival.
dwPortTimeoutErr
Specifies the total number of time-out errors on the port. Time-out errors occur when an expected character is not received in time. When this occurs, the software assumes that the data has been lost and requests that it be resent.
dwPortAlignmentErr
Specifies the total number of alignment errors on the port. Alignment errors occur when a character received is not the one expected. This usually happens when a character is lost or when a time-out error occurs.
dwPortHardwareOverrunErr
Specifies the total number of hardware overrun errors on the port. These errors indicate the number of times the sending computer has transmitted characters faster than the receiving computer hardware can process them. If this problem persists, reduce the BPS connection rate on the client.
dwPortFramingErr
Specifies the total number of framing errors on the port. A framing error occurs when an asynchronous character is received with an invalid start or stop bit.
dwPortBufferOverrunErr
Specifies the total number of buffer overrun errors on the port. A buffer overrun error occurs when the sending computer is transmitting characters faster than the receiving computer can accommodate them. If this problem persists, reduce the BPS connection rate on the client.
dwPortBytesXmitedUncompressed
Specifies the total number of bytes transmitted uncompressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesRcvedUncompressed
Specifies the total number of bytes received uncompressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesXmitedCompressed
Specifies the total number of bytes transmitted compressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesRcvedCompressed
Specifies the total number of bytes received compressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_0, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortClearStatistics, RasAdminPortGetInfo


RAS_PPP_ATCP_RESULT

The RAS_PPP_ATCP_RESULT structure is used to report the result of an AppleTalk protocol projection operation for a port. Windows NT version 4.0 does not use this structure.

typedef struct _RAS_PPP_ATCP_RESULT {
    DWORD dwError;
    WCHAR wszAddress[ RAS_ATADDRESSLEN + 1 ];
} RAS_PPP_ATCP_RESULT;

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PPP_PROJECTION_RESULT


RAS_PPP_IPCP_RESULT

The RAS_PPP_IPCP_RESULT structure is used to report the result of a PPP Internet Protocol (IP) projection operation for a port.

typedef struct _RAS_PPP_IPCP_RESULT {
    DWORD dwError;
    WCHAR wszAddress[ RAS_IPADDRESSLEN + 1 ];
} RAS_PPP_IPCP_RESULT;

Members

dwError
Indicates the results of the IP projection operation. A value of NO_ERROR indicates success, in which case, the wszAddress member is valid. If the projection operation was not successful, dwError is an error code from WINERROR.H or RASERROR.H.
wszAddress
A null-terminated Unicode string that specifies the IP address assigned to the remote client. This string has the "a.b.c.d" form.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_IPXCP_RESULT

The RAS_PPP_IPXCP_RESULT structure is used to report the result of a PPP Internetwork Packet Exchange (IPX) projection operation for a port.

typedef struct _RAS_PPP_IPXCP_RESULT {
    DWORD dwError;
    WCHAR wszAddress[ RAS_IPXADDRESSLEN + 1 ];
} RAS_PPP_IPXCP_RESULT;

Members

dwError
Indicates the results of the IPX projection operation. A value of NO_ERROR indicates success, in which case, the wszAddress member is valid. If the projection operation was not successful, dwError is an error code from WINERROR.H or RASERROR.H.
wszAddress
A null-terminated Unicode string that specifies the IPX address assigned to the remote client. This string has the "net.node" form.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_NBFCP_RESULT

The RAS_PPP_NBFCP_RESULT structure is used to report the result of a PPP NetBEUI Framer (NBF) projection operation for a port.

typedef struct _RAS_PPP_NBFCP_RESULT {
    DWORD dwError;
    DWORD dwNetBiosError;
    CHAR  szName[ NETBIOS_NAME_LEN + 1 ];
    WCHAR wszWksta[ NETBIOS_NAME_LEN + 1 ];
} RAS_PPP_NBFCP_RESULT;

Members

dwError
Indicates the results of the NBF projection operation. A value of NO_ERROR indicates success, in which case, the wszWksta member contains the name of the remote computer. If the projection operation was not successful, dwError is an error code from WINERROR.H or RASERROR.H.
dwNetBiosError
Ignore this member on the server; it is relevant only on the client.
szName
Ignore this member on the server; it is relevant only on the client.
wszWksta
A null-terminated Unicode string that specifies the NetBIOS name of the RAS client workstation.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_PROJECTION_RESULT

The RAS_PPP_PROJECTION_RESULT structure is used to report the results of the various PPP projection operations for a port.

typedef struct _RAS_PPP_PROJECTION_RESULT {
    RAS_PPP_NBFCP_RESULT nbf;
    RAS_PPP_IPCP_RESULT  ip;
    RAS_PPP_IPXCP_RESULT ipx;
    RAS_PPP_ATCP_RESULT  at;
} RAS_PPP_PROJECTION_RESULT;

Members

nbf
A RAS_PPP_NBFCP_RESULT structure that reports the result of a PPP NetBEUI Framer (NBF) projection operation.
ip
A RAS_PPP_IPCP_RESULT structure that reports the result of a PPP Internet Protocol (IP) projection operation.
ipx
A RAS_PPP_IPXCP_RESULT structure that reports the result of a PPP Internetwork Packet Exchange (IPX) projection operation.
at
A RAS_PPP_ATCP_RESULT structure. Windows NT version 4.0 does not use this member.

Remarks

This structure reports the projection results for NetBEUI, TCP/IP, and IPX protocols. Each PPP structure has a dwError member that indicates whether the other information in the structure is valid. If dwError is NO_ERROR, the other information is valid. If dwError is one of the error codes in WINERROR.H or RASERROR.H, the other information is not valid.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RAS_PORT_1, RAS_PPP_ATCP_RESULT, RAS_PPP_IPCP_RESULT, RAS_PPP_IPXCP_RESULT, RAS_PPP_NBFCP_RESULT, RasAdminPortGetInfo


RAS_SECURITY_INFO

The RAS_SECURITY_INFO structure is used with the RasSecurityDialogGetInfo function to return information about the RAS port associated with a RAS security DLL authentication transaction.

typedef struct _RAS_SECURITY_INFO {
    DWORD LastError;
    DWORD BytesReceived;
    CHAR DeviceName[RASSAPI_MAX_DEVICE_NAME+1];
}RAS_SECURITY_INFO,*PRAS_SECURITY_INFO;

Members

LastError
Specifies an error code that indicates the state of the last RasSecurityDialogReceive call for the port. If the receive operation failed, LastError is one of the error codes defined in RASERROR.H or WINERROR.H. Otherwise, LastError is one of the following values.
Value | Meaning
SUCCESS | The receive operation has been successfully completed. The BytesReceived member indicates the number of bytes received.
PENDING | The receive operation is pending completion.

BytesReceived
Specifies the number of bytes received in the most recent RasSecurityDialogReceive operation. This member is valid only if the value of the LastError member is SUCCESS.
DeviceName
Specifies a null-terminated string that contains the user-friendly display name of the device on the port, such as Hayes SmartModem 9600.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasSecurityDialogGetInfo, RasSecurityDialogReceive


RAS_SERVER_0

The RAS_SERVER_0 structure is used by the RasAdminServerGetInfo function to return information about the ports configured on a RAS Server.

typedef struct _RAS_SERVER_0 {
    WORD  TotalPorts;   // total ports available for connection
    WORD  PortsInUse;   // ports currently in use by remote clients
    DWORD RasVersion;   // version of RAS server
} RAS_SERVER_0, *PRAS_SERVER_0;

Members

TotalPorts
Specifies the total number of ports configured on the RAS server that are available for remote clients to connect to. For example, if the total number of ports configured for dialing in to a server is four, but one of the ports is currently in use for dialing out, TotalPorts will be three.
PortsInUse
Specifies the number of ports currently in use by remote clients.
RasVersion
Specifies the version of the RAS server. You can use this information to take version-specific action. This member can be one of the following values.
Value | Description
RASDOWNLEVEL | Indicates a LAN Manager version 1.0 RAS server.
RASADMIN_35 | Indicates a Windows NT version 3.5 or 3.51 RAS server or client.
RASADMIN_CURRENT | Indicates a Windows NT version 4.0 RAS server or client.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasAdminServerGetInfo


RAS_USER_0

The RAS_USER_0 structure is used in the RasAdminUserSetInfo and RasAdminUserGetInfo functions to specify information about a user.

typedef struct _RAS_USER_0 {
    BYTE  bfPrivilege;
    WCHAR szPhoneNumber[ RASSAPI_MAX_PHONENUMBER_SIZE + 1];
} RAS_USER_0, *PRAS_USER_0;

Members

bfPrivilege
A set of bit flags that specify the RAS privileges of the user. This member can be a combination of the RASPRIV_DialinPrivilege flag and one of the call-back flags. Note that when you call the RasAdminUserSetInfo function, you must specify one of the call-back flags. You can use the RASPRIV_CallbackType mask to identify the type of call-back privilege provided to the user. The following flags are defined.
Value | Meaning
RASPRIV_NoCallback | The user has no call-back privilege.
RASPRIV_AdminSetCallback | The user account is configured to have the administrator set the call-back number.
RASPRIV_CallerSetCallback | The remote user can specify a call-back phone number when dialing in.
RASPRIV_DialinPrivilege | The user has permission to dial in to this server.

szPhoneNumber
A null-terminated Unicode string that specifies the call-back phone number for the user.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasAdminUserGetInfo, RasAdminUserSetInfo


RASADPARAMS

The RASADPARAMS structure describes the parameters that AutoDial passes to a RASADFunc AutoDial handler.

typedef struct tagRASADPARAMS {
    DWORD       dwSize;
    HWND        hwndOwner;
    DWORD       dwFlags;
    LONG        xDlg;
    LONG        yDlg;
} RASADPARAMS;

Members

dwSize
Specifies the size, in bytes, of the RASADPARAMS structure. The system sets dwSize to sizeof(RASADPARAMS) to identify the version of the structure.
hwndOwner
Specifies the parent window for the AutoDial user interface. This member can be NULL.
dwFlags
Specifies a flag that indicates how to position the window of your AutoDial user interface. The following flag is defined.
Flag Description
RASADFLG_PositionDlg If this flag is set, position your window according to the coordinates specified by the xDlg and yDlg members.

If this flag is not set, center your window on the window specified by the hwndOwner member. If hwndOwner is NULL, center your window on the screen.

xDlg
Specifies the horizontal screen coordinate of your window's upper-left corner. Ignore this member if the RASADFLG_PositionDlg bit is not set in the dwFlags member.
yDlg
Specifies the vertical screen coordinate of your window's upper-left corner. Ignore this member if the RASADFLG_PositionDlg bit is not set in the dwFlags member.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RASADFunc


RASAMB

The RASAMB structure contains the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

The RasGetProjectionInfo function returns a RASAMB data structure when its rasprojection parameter has the value RASP_Amb.

typedef  struct  _RASAMB {
    DWORD    dwSize;
    DWORD    dwError;
    TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];
     BYTE     bLana;
} RASAMB;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASAMB). The function can then determine the version of the RASAMB data structure that the caller of RasGetProjectionInfo is expecting. This allows backward compatibility for compiled applications if there are future enhancements to the data structure.
dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.
szNetBiosError
If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.
bLana
Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Remarks

The AMB protocol is used with servers that were released before PPP was adopted as the primary framing protocol; for example, Windows NT 3.1 and OS/2 1.3 RAS servers.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetProjectionInfo, RASPROJECTION


RASAUTODIALENTRY

The RASAUTODIALENTRY structure describes an AutoDial entry associated with a network address in the AutoDial mapping database. An AutoDial entry specifies a phone-book entry that AutoDial dials in a particular TAPI dialing location.

The RasGetAutodialAddress and RasSetAutodialAddress functions use this structure to set and retrieve information about an AutoDial entry.

typedef struct {
    DWORD    dwSize;
    DWORD    dwFlags;
    DWORD    dwDialingLocation;
    TCHAR    szEntry[RAS_MaxEntryName + 1];
} RASAUTODIALENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASAUTODIALENTRY structure. Before calling RasGetAutodialAddress or RasSetAutodialAddress, set dwSize to sizeof(RASAUTODIALENTRY) to identify the version of the structure.
dwFlags
Reserved; must be zero.
dwDialingLocation
Specifies a TAPI dialing location. For more information about TAPI dialing locations, see the Win32 Telephony (TAPI) Programmer's Reference.
szEntry
Specifies a null-terminated string that names an existing phone-book entry.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetAutodialAddress, RasSetAutodialAddress


RASCONN

The RASCONN structure provides information about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.

typedef struct _RASCONN {
    DWORD     dwSize;
    HRASCONN  hrasconn;
    TCHAR     szEntryName[RAS_MaxEntryName + 1];

#if (WINVER >= 0x400)
    CHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
    CHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
#endif

} RASCONN ;

Members

dwSize
Specifies the size, in bytes, of the RASCONN structure.
hrasconn
Specifies the remote access connection. This handle is used in other remote access API calls.
szEntryName
A string that specifies the phone-book entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a "." followed by the connection phone number.
szDeviceType
A null-terminated string that contains the device type through which the connection is made.
szDeviceName
A null-terminated string that contains the device name through which the connection is made.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasEnumConnections, RasGetConnectStatus


RASCONNSTATUS

A RASCONNSTATUS structure describes the current status of a remote access connection. It is returned by the RasGetConnectStatus function.

typedef struct _RASCONNSTATUS {
    DWORD         dwSize;
    RASCONNSTATE  rasconnstate;
    DWORD         dwError;
    TCHAR         szDeviceType[RAS_MaxDeviceType + 1];
    TCHAR         szDeviceName[RAS_MaxDeviceName + 1];
} RASCONNSTATUS;

Members

dwSize
Specifies the structure size, in bytes.
rasconnstate
Specifies a RASCONNSTATE enumerator value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.

Two state values are especially significant:
State | Meaning
RASCS_Connected | Indicates that the connection has been successfully established.
RASCS_Disconnected | Indicates that the connection has failed.

dwError
If nonzero, indicates the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.
szDeviceType
A string that specifies the type of the current device, if available. For example, common device types supported by RAS are "modem", "pad", "switch", "isdn", or "null".
szDeviceName
A string that specifies the name of the current device, if available. This would be the name of the modem — for example, "Hayes Smartmodem 2400"; the name of the PAD, for example "US Sprint"; or the name of a switch device, for example "Racal-Guardata".

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetConnectStatus, RasDial, RASCONNSTATE


RASCREDENTIALS

The RASCREDENTIALS structure is used with the RasGetCredentials and RasSetCredentials functions to specify the user credentials associated with a RAS phone-book entry.

typedef struct {
    DWORD dwSize;
    DWORD dwMask;
    TCHAR szUserName[UNLEN + 1];
    TCHAR szPassword[PWLEN + 1];
    TCHAR szDomain[DNLEN + 1];
} RASCREDENTIALS, *LPRASCREDENTIALS;

Members

dwSize
Specifies the size, in bytes, of the RASCREDENTIALS structure.
dwMask
A set of bit flags that specify the members of this structure that are valid. On input, set the flags to indicate the members in which you are interested. On output, the function sets the flags to indicate the members that contain valid data. This member can be a combination of the following values.
Value | Meaning
RASCM_UserName | The szUserName member is valid.
RASCM_Password | The szPassword member is valid.
RASCM_Domain | The szDomain member is valid.

szUserName
A null-terminated string that contains a user name.
szPassword
A null-terminated string that contains a password.
szDomain
A null-terminated string that contains a domain name.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetCredentials, RasSetCredentials


RASCTRYINFO

The RASCTRYINFO structure describes the direct dialing procedures for calls placed within a specified country. The RasGetCountryInfo function uses this structure to retrieve country-specific dialing information from the Windows Telephony list of country information.

For more information about country-specific dialing information, see the Win32 Telephony (TAPI) Programmer's Reference.

typedef struct RASCTRYINFO {
    DWORD   dwSize;
    DWORD   dwCountryID;
    DWORD   dwNextCountryID;
    DWORD   dwCountryCode;
    DWORD   dwCountryNameOffset;
} RASCTRYINFO;

Members

dwSize
Specifies the size, in bytes, of the RASCTRYINFO structure. Before calling RasGetCountryInfo, set dwSize to sizeof(RASCTRYINFO) to identify the version of the structure.
dwCountryID
Specifies a TAPI country identifier. Before calling RasGetCountryInfo, set dwCountryID to identify the country of interest. For more information about TAPI country identifiers, see the Win32 Telephony (TAPI) Programmer's Reference.

If this member is 1, RasGetCountryInfo returns information about the first country in the Windows Telephony list of country information.

dwNextCountryID
Specifies the TAPI country identifier of the next country to enumerate in the Windows Telephony list. This member is zero for the last country in the list.
dwCountryCode
Specifies the country code for the country identified by the dwCountryID member.
dwCountryNameOffset
Specifies the offset, in bytes, from the start of the structure to the start of a null-terminated string describing the country. The description string is either ANSI or Unicode, depending on whether you use the ANSI or Unicode version of RasGetCountryInfo.

Remarks

For more information on dialing procedures and telephony configuration, see the Win32 Telephony (TAPI) Programmer's Reference.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetCountryInfo


RASDEVINFO

The RASDEVINFO structure contains information that describes a TAPI device capable of establishing a RAS connection. The RasEnumDevices function uses this structure to retrieve information about RAS-capable devices.

typedef struct tagRASDEVINFO {
    DWORD    dwSize;
    TCHAR    szDeviceType[ RAS_MaxDeviceType + 1 ];
    TCHAR    szDeviceName[ RAS_MaxDeviceName + 1 ];
} RASDEVINFOW;

Members

dwSize
Specifies the size, in bytes, of the RASDEVINFO structure. Before calling RasEnumDevices, set dwSize to sizeof(RASDEVINFO) to identify the version of the structure.
szDeviceType
Specifies a null-terminated string indicating the RAS device type referenced by szDeviceName. This member can be one of the following string constants.
String | Description
RASDT_Modem | A modem accessed through a COM port.
RASDT_Isdn | An ISDN card with the corresponding NDISWAN driver installed.
RASDT_X25 | An X.25 card with the corresponding NDISWAN driver installed.
RASDT_Vpn | A virtual private network connection.
RASDT_Pad | A Packet Assembler/Disassembler.

Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and RASDT_Pad device types are not supported on Windows 95.

Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, the RASDT_X25 and RASDT_Pad device types are not currently supported on Windows 98

szDeviceName
Specifies a null-terminated string containing the name of a TAPI device.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasEnumDevices


RASDIALDLG

The RASDIALDLG structure is used in the RasDialDlg function to specify additional input and output parameters.

typedef struct tagRASDIALDLG {
    IN  DWORD          dwSize;
    IN  HWND           hwndOwner;
    IN  DWORD          dwFlags;
    IN  LONG           xDlg;
    IN  LONG           yDlg;
    IN  DWORD          dwSubEntry;
    OUT DWORD          dwError;
    IN  DWORD          reserved;
    IN  DWORD          reserved2;
} RASDIALDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasDialDlg, set this member to sizeof(RASDIALDLG) to indicate the version of the structure. If dwSize is not a valid size, RasDialDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Identifies the window that owns the modal RasDialDlg dialog boxes. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A bit flag that indicates the options that are enabled for the dialog box. You can specify the following value.
Value Meaning
RASDDFLAG_PositionDlg If this flag is set, RasDialDlg uses the values specified by the xDlg and yDlg members to position the dialog box.

If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASDDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASDDFLAG_PositionDlg flag is set.
dwSubEntry
Indicates the subentry or subentries to dial. If dwSubEntry is zero, RasDialDlg dials all subentries associated with the specified phone-book entry. Otherwise, to indicate the index of the individual subentry to dial, dwSubEntry must be a number from one to the number of subentries.
dwError
The RasDialDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasDialDlg


RASDIALEXTENSIONS

The RASDIALEXTENSIONS structure contains information about extended features of the RasDial function. You can enable one or more of these extensions by passing a pointer to a RASDIALEXTENSIONS structure when you call RasDial. If you do not pass a pointer to a RASDIALEXTENSIONS structure to RasDial, RasDial uses the default settings that are noted following.

typedef  struct  _RASDIALEXTENSIONS {
    DWORD    dwSize;
    DWORD    dwfOptions;
    HWND    hwndParent;
    DWORD    reserved;
} RASDIALEXTENSIONS;

Members

dwSize
Specifies the size of this structure, in bytes. Set this member to sizeof(RASDIALEXTENSIONS). This indicates the version of the structure.
dwfOptions
A set of bit flags that specify RasDial extensions. The following bit flags are defined; you must set all undefined bits to zero:
Value | Description
RDEOPT_UsePrefixSuffix If this bit flag is one, RasDial uses the prefix and suffix that is in the RAS phone book.

If this bit flag is zero, RasDial ignores the prefix and suffix that is in the RAS phone book.

If no phone-book entry name is specified in the call to RasDial, the actual value of this bit flag is ignored, and it is assumed to be zero.
RDEOPT_PausedStates If this bit flag is one, RasDial accepts paused states. Examples of paused states are terminal mode, retry logon, change password, and set callback number.

If this bit flag is zero, RasDial reports a fatal error if it enters a paused state.

RDEOPT_IgnoreModemSpeaker If this bit flag is one, RasDial ignores the modem speaker setting that is in the RAS phone book, and uses the setting specified by the RDEOPT_SetModemSpeaker bit flag.

If this bit flag is zero, RasDial uses the modem speaker setting that is in the RAS phone book, and ignores the setting specified by the RDEOPT_SetModemSpeaker bit flag.

If no phone-book entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetModemSpeaker bit flag. The default setting is used if RDEOPT_IgnoreModemSpeaker is zero. The setting specified by RDEOPT_SetModemSpeaker is used if RDEOPT_IgnoreModemSpeaker is one.
RDEOPT_SetModemSpeaker If this bit flag is one, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker on.

If this bit flag is zero, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker off.

If RDEOPT_IgnoreModemSpeaker is zero, RasDial ignores the value of RDEOPT_SetModemSpeaker, and sets the modem speaker based on the RAS phone-book setting or the default setting.
RDEOPT_IgnoreSoftwareCompression If this bit flag is one, RasDial ignores the software compression setting that is in the RAS phone book, and uses the setting specified by the RDEOPT_SetSoftwareCompression bit flag.

If this bit flag is zero, RasDial uses the software compression setting that is in the RAS phone book, and ignores the setting specified by the RDEOPT_SetSoftwareCompression bit flag.

If no phone-book entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetSoftwareCompression bit flag. The default setting is used if RDEOPT_IgnoreSoftwareCompression is zero. The setting specified by RDEOPT_SetSoftwareCompression is used if RDEOPT_IgnoreSoftwareCompression is one.
RDEOPT_SetSoftwareCompression If this bit flag is one, and RDEOPT_IgnoreSoftwareCompression is one, RasDial uses software compression.

If this bit flag is zero, and RDEOPT_IgnoreSoftwareCompression is one, RasDial does not use software compression.

If RDEOPT_IgnoreSoftwareCompression is zero, RasDial ignores the value of RDEOPT_SetSoftwareCompression, and sets the software compression state based on the RAS phone-book setting or the default setting.
RDEOPT_PauseOnScript | Used internally by the RasDialDlg function so that a Windows-95-style logon script is executed in a terminal window visible to the user. Applications should not set this flag.

The default value for each of these bit flags is zero.

hwndParent
Handle to a parent window that a security DLL can use for dialog box creation and centering.

Note that this is not the window that receives RasDial progress notifications.

This member is optional; it is not required when no security DLL is defined.

The default value for this member is NULL.

reserved
This member is reserved for future use. It must be set to zero.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasDial


RASDIALPARAMS

The RASDIALPARAMS structure contains parameters used by RasDial to establish a remote access connection.

typedef struct _RASDIALPARAMS {
   DWORD  dwSize;
   TCHAR  szEntryName[RAS_MaxEntryName + 1];
   TCHAR  szPhoneNumber[RAS_MaxPhoneNumber + 1];
   TCHAR  szCallbackNumber[RAS_MaxCallbackNumber + 1];
   TCHAR  szUserName[UNLEN + 1];
   TCHAR  szPassword[PWLEN + 1];
   TCHAR  szDomain[DNLEN + 1] ;
#if (WINVER >= 0x401)
   DWORD  dwSubEntry;
   DWORD  dwCallbackId;
#endif
} RASDIALPARAMS;

Members

dwSize
Specifies the structure size, in bytes.
szEntryName
Specifies a string containing the phone-book entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a nonempty szPhoneNumber must be provided.
szPhoneNumber
Specifies a string containing an overriding phone number. An empty string ("") indicates that the phone-book entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".
szCallbackNumber
Specifies a string containing a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phone book should be used for callback.
szUserName
Specifies a string containing the user's user name. This string is used to authenticate the user's access to the remote access server.
szPassword
Specifies a string containing the user's password. This string is used to authenticate the user's access to the remote access server.

Windows NT: You can use szPassword to send a new password to the remote server when you restart a RasDial connection from a RASCS_PasswordExpired paused state. When changing a password on an entry that calls Microsoft Networks, you should limit the new password to 14 characters in length to avoid down-level compatibility problems.

szDomain
Specifies a string containing the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phone book for the entry.
dwSubEntry
Specifies the index of the initial subentry to dial. If the phone-book entry has no subentries or the dial mode of the phone-book entry is RASEDM_DialAll, dwSubEntry is ignored. If the dial mode is RASEDM_DialAsNeeded, RAS dials the specified subentry. If dwSubEntry is not a valid subentry index, RAS dials the first subentry. The RASENTRY structure returned by RasGetEntryProperties indicates the dial mode and number of subentries for the phone-book entry.
dwCallbackId
Specifies an application-defined value that RAS passes to your RasDialFunc2 callback function.

Remarks

The szUserName and szPassword strings are used to authenticate the user's access to the remote access server.

Windows NT: RAS does not actually log the user onto the network. The user does this in the usual manner, for example, by logging on with cached credentials prior to making the connection or by using ctrl+alt+del, after the RAS connection is established.

If both the szUserName and szPassword members are empty strings (""), RAS uses the user name and password of the current logon context for authentication. For a user mode application, RAS uses the credentials of the currently logged-on interactive user. For a Win32 service process, RAS uses the credentials associated with the service.

Windows 95: RAS uses the szUserName and szPassword strings to log the user onto the network.

Windows 95 cannot get the password of the currently logged-on user, so if both the szUserName and the szPassword members are empty strings (""), RAS leaves the user name and password empty during authentication.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasDial


RASENTRY

The RASENTRY structure describes a phone-book entry. The RasSetEntryProperties and RasGetEntryProperties functions use this structure to set and retrieve the properties of a phone-book entry.

typedef struct tagRASENTRY {
  DWORD      dwSize;
  DWORD      dwfOptions;
  //
  // Location/phone number.
  //
  DWORD      dwCountryID;
  DWORD      dwCountryCode;
  TCHAR      szAreaCode[ RAS_MaxAreaCode + 1 ];
  TCHAR      szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  DWORD      dwAlternateOffset;
  //
  // PPP/Ip
  //
  RASIPADDR  ipaddr;
  RASIPADDR  ipaddrDns;
  RASIPADDR  ipaddrDnsAlt;
  RASIPADDR  ipaddrWins;
  RASIPADDR  ipaddrWinsAlt;
  //
  // Framing
  //
  DWORD      dwFrameSize;
  DWORD      dwfNetProtocols;
  DWORD      dwFramingProtocol;
  //
  // Scripting
  //
  TCHAR      szScript[ MAX_PATH ];
  //
  // AutoDial
  //
  TCHAR       szAutodialDll[ MAX_PATH ];
  TCHAR       szAutodialFunc[ MAX_PATH ];
  //
  // Device
  //
  TCHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
  //
  // X.25
  //
  TCHAR      szX25PadType[ RAS_MaxPadType + 1 ];
  TCHAR      szX25Address[ RAS_MaxX25Address + 1 ];
  TCHAR      szX25Facilities[ RAS_MaxFacilities + 1 ];
  TCHAR      szX25UserData[ RAS_MaxUserData + 1 ];
  DWORD      dwChannels;
  //
  // Reserved
  //
  DWORD       dwReserved1;
  DWORD       dwReserved2;
#if (WINVER >= 0x401)
  //
  // Multilink
  //
  DWORD       dwSubEntries;
  DWORD       dwDialMode;
  DWORD       dwDialExtraPercent;
  DWORD       dwDialExtraSampleSeconds;
  DWORD       dwHangUpExtraPercent;
  DWORD       dwHangUpExtraSampleSeconds;
  //
  // Idle timeout
  //
  DWORD       dwIdleDisconnectSeconds;
#endif
#if (WINVER >= 0x500)
  //
  // Port Name
  //
  TCHAR       szPortName[ RAS_MaxDeviceName + 1 ];
#endif
} RASENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASENTRY structure. Before calling RasSetEntryProperties or RasGetEntryProperties, set dwSize to sizeof(RASENTRY) to identify the version of the structure.
dwfOptions
A set of bit flags that specify connection options. You can set one or more of the following flags.
Flag | Description
RASEO_UseCountryAndAreaCodes If this flag is set, the dwCountryID, dwCountryCode, and szAreaCode members are used to construct the phone number. If this flag is not set, these members are ignored.

This flag corresponds to the Use Country and Area Codes check box in the Phone dialog box.
RASEO_SpecificIpAddr If this flag is set, RAS tries to use the IP address specified by ipaddr as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored.

Setting the RASEO_SpecificIpAddr flag corresponds to selecting the Specify an IP Address setting in the TCP/IP settings dialog box. Clearing the RASEO_SpecificIpAddr flag corresponds to selecting the Server Assigned IP Address setting in the TCP/IP settings dialog box.

Currently, an IP address set in the phone-book entry properties or retrieved from a server overrides the IP address set in the network control panel.

RASEO_SpecificNameServers If this flag is set, RAS uses the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt members to specify the name server addresses for the dial-up connection. If this flag is not set, RAS ignores these members.

Setting the RASEO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the RASEO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.
RASEO_IpHeaderCompression If this flag is set, RAS negotiates to use IP header compression on PPP connections.

If this flag is not set, IP header compression is not negotiated.

This flag corresponds to the Use IP Header Compression check box in the TCP/IP settings dialog box. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.
RASEO_RemoteDefaultGateway If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified.

This flag corresponds to the Use Default Gateway on Remote Network check box in the TCP/IP settings dialog box.
RASEO_DisableLcpExtensions | If this flag is set, RAS disables the PPP LCP extensions defined in RFC 1570. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server callback. Do not set this flag unless specifically required.
RASEO_TerminalBeforeDial If this flag is set, RAS displays a terminal window for user input before dialing the connection.
RASEO_TerminalAfterDial If this flag is set, RAS displays a terminal window for user input after dialing the connection.

Do not set this flag if a dial-up networking script is to be associated with the connection, because scripting has its own terminal implementation.
RASEO_ModemLights | This flag is currently ignored.
RASEO_SwCompression | If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP driver to attempt to negotiate CCP with the server. This flag should be set by default, but clearing it can reduce the negotiation period if the server does not support a compatible compression protocol.
RASEO_RequireEncryptedPw If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. The CHAP and SPAP authentication protocols are also supported. Clear this flag for increased interoperability, and set it for increased security.

This flag corresponds to the Require Encrypted Password check box in the Security dialog box. See also RASEO_RequireMsEncryptedPw.
RASEO_RequireMsEncryptedPw If this flag is set, only Microsoft's secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PPP plain-text authentication protocol, MD5-CHAP, MS-CHAP, or SPAP. The flag should be cleared for maximum interoperability and should be set for maximum security. This flag takes precedence over RASEO_RequireEncryptedPw.

This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also RASEO_RequireDataEncryption.
RASEO_RequireDataEncryption If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.

This flag corresponds to the Require Data Encryption check box in the Security dialog box.
RASEO_NetworkLogon If this flag is set, RAS logs on to the network after the point-to-point connection is established.

This flag currently has no effect under Windows NT.
RASEO_UseLogonCredentials If this flag is set, RAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.

Note that this setting is ignored by the RasDial function, where specifying empty strings for the szUserName and szPassword members of the RASDIALPARAMS structure gives the same result.

This flag corresponds to the Use Current Username and Password check box in the Security dialog box.
RASEO_PromoteAlternates This flag has an effect when alternate phone numbers are defined by the dwAlternateOffset member. If this flag is set, an alternate phone number that connects successfully becomes the primary phone number, and the current primary phone number is moved to the alternate list.

This flag corresponds to the check box in the Alternate Numbers dialog box.
RASEO_SecureLocalFiles | Windows NT only: If this flag is set, RAS checks for existing remote file system and remote printer bindings before making a connection with this entry. Typically, you set this flag on phone-book entries for public networks to remind users to break connections to their private network before connecting to a public network.

dwCountryID
Specifies the TAPI country identifier. Use the RasGetCountryInfo function to enumerate country identifiers. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.
dwCountryCode
Specifies the country code portion of the phone number. The country code must correspond to the country identifier specified by dwCountryID. If dwCountryCode is zero, the country code is based on the country identifier specified by dwCountryID. This member is ignored unless dwfOptions specifies the RASEO_UseCountryAndAreaCodes flag.
szAreaCode
Specifies the area code as a null-terminated string. If the dialing location does not have an area code, specify an empty string (""). Do not include parentheses or other delimiters in the area code string. (For example, "206" is a valid area code; "(206)" is not. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.
szLocalPhoneNumber
Specifies a null-terminated string containing a telephone number. The way RAS uses this string depends on whether the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag. If the flag is set, RAS combines szLocalPhoneNumber with the country and area codes specified by the dwCountryID, dwCountryCode , and szAreaCode members. If the flag is not set, RAS uses the szLocalPhoneNumber string as the entire phone number.
dwAlternateOffset
Specifies the offset, in bytes, from the beginning of the structure to a list of consecutive null-terminated strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that RAS dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect. The alternate phone number strings are ANSI or Unicode, depending on whether you use the ANSI or Unicode version of the structure.
ipaddr
Specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificIpAddr flag.
ipaddrDns
Specifies the IP address of the DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrDnsAlt
Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWins
Specifies the IP address of the WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWinsAlt
Specifies the IP address of a secondary WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
dwFrameSize
Specifies the network protocol frame size. The value should be either 1006 or 1500. This member is ignored unless dwFramingProtocol specifies the RASFP_Slip flag.
dwfNetProtocols
Specifies the network protocols to negotiate. This member can be a combination of the following flags.
Flag | Description
RASNP_NetBEUI | Negotiate the NetBEUI protocol.
RASNP_Ipx | Negotiate the IPX protocol.
RASNP_Ip | Negotiate the TCP/IP protocol.

dwFramingProtocol
Specifies the framing protocol used by the server. PPP is the emerging standard. SLIP is used mainly in UNIX environments. This member can be one of the following flags.
Flag | Description
RASFP_Ppp | Point-to-Point Protocol (PPP)
RASFP_Slip | Serial Line Internet Protocol (SLIP)
RASFP_Ras | Asynchronous NetBEUI, Microsoft proprietary protocol implemented in Windows NT 3.1 and Windows for Workgroups 3.11

To use Compressed SLIP, set the RASFP_Slip flag and set the RASEO_IpHeaderCompression flag in the dwfOptions member.

Windows NT 5.0 or later: The RASFP_Ras flag is no longer supported. As a result, Windows NT 5.0 and later computers will not be able to connect to Lan Manager, Windows for Workgroups 3.11, or Windows NT 3.1 servers. However, these earlier platforms will continue to be able to connect to Windows NT 5.0 and later servers.

szScript
Specifies a null-terminated string containing the name of the script file. The filename should be a full path.

Windows NT: To indicate a Windows NT SWITCH.INF script name, set the first character of the name to "[".

szAutodialDll
Specifies a null-terminated string containing the full path and filename of the dynamic-link library (DLL) for the customized AutoDial handler. If szAutodialDll contains an empty string (""), RAS uses the default dialing user interface and the szAutodialFunc member is ignored.
szAutodialFunc
Specifies a null-terminated string containing the exported name of the RASADFunc function for the customized AutoDial handler. An AutoDial DLL must provide both ANSI and Unicode versions of the RASADFunc handler. However, do not include the "A" or "W" suffix in the name specified by szAutodialFunc.
szDeviceType
Specifies a null-terminated string indicating the RAS device type referenced by szDeviceName. This member can be one of the following string constants.
String | Description
RASDT_Modem | A modem accessed through a COM port.
RASDT_Isdn | An ISDN card with corresponding NDISWAN driver installed.
RASDT_X25 | An X.25 card with corresponding NDISWAN driver installed.
RASDT_Vpn | A virtual private network connection.
RASDT_Pad | A Packet Assembler/Disassembler.

Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and RASDT_Pad device types are not supported on Windows 95.

Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, the RASDT_X25 and RASDT_Pad device types are not currently supported on Windows 98

szDeviceName
Contains a null-terminated string containing the name of a TAPI device to use with this phone-book entry. To enumerate all available RAS-capable devices, use the RasEnumDevices function.
szX25PadType
Contains a null-terminated string that identifies the X.25 PAD type. Set this member to "" unless the entry should dial using an X.25 PAD.

Windows NT: Under Windows NT, the szX25PadType string maps to a section name in PAD.INF.

szX25Address
Contains a null-terminated string that identifies the X.25 address to connect to. Set this member to "" unless the entry should dial using an X.25 PAD or native X.25 device.
szX25Facilities
Contains a null-terminated string that specifies the facilities to request from the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").
szX25UserData
Contains a null-terminated string that specifies additional connection information supplied to the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").
dwChannels;
dwReserved1
Reserved; must be zero.
dwReserved2
Reserved; must be zero.
dwSubEntries
Specifies the number of multilink subentries associated with this entry. When calling RasSetEntryProperties, set this member to zero. To add subentries to a phone-book entry, use the RasSetSubEntryProperties function.
dwDialMode
Windows NT 5.0 or later: Indicates whether RAS should dial all of this entry's multilink subentries when the entry is first connected. This member can be one of the following values.
Value | Meaning
RASEDM_DialAll | Dial all subentries initially.
RASEDM_DialAsNeeded | Adjust the number of subentries as bandwidth is needed. RAS uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwDialHangUpExtraPercent, and dwHangUpExtraSampleSeconds members to determine when to dial or disconnect a subentry.

dwDialExtraPercent
Windows NT 5.0 or later: Specifies a percent of the total bandwidth available from the currently connected subentries. RAS dials an additional subentry when the total bandwidth used exceeds dwDialExtraPercent percent of the available bandwidth for at least dwDialExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwDialExtraSampleSeconds
Windows NT 5.0 or later: Specifies the number of seconds that current bandwidth usage must exceed the threshold specified by dwDialExtraPercent before RAS dials an additional subentry.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwHangUpExtraPercent
Windows NT 5.0 or later: Specifies a percent of the total bandwidth available from the currently connected subentries. RAS terminates (hangs up) an existing subentry connection when total bandwidth used is less than dwHangUpExtraPercent percent of the available bandwidth for at least dwHangUpExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwHangUpExtraSampleSeconds
Windows NT 5.0 or later: Specifies the number of seconds that current bandwidth usage must be less than the threshold specified by dwHangUpExtraPercent before RAS terminates an existing subentry connection.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwIdleDisconnectSeconds
Specifies the number of seconds after which the connection is terminated due to inactivity. Note that unless the idle timeout is disabled, the entire connection is terminated if the connection is idle for the specified interval. This member can specify a number of seconds, or one of the following values.
Value | Meaning
RASIDS_Disabled | There is no idle timeout for this connection.
RASIDS_UseGlobalValue | Use the user preference value as the default.

szPortName
Specifies a null-terminated string containing the name of the port. The port name will depend on the RAS device type. For example, typical port names for a modem device would be "COM1" or "COM2.". For virtual private networks, the port name identifies the VPN connection.

Remarks

Unless the operating system is Windows NT 5.0 or later, the RAS Connection Manager ignores the dwDialMode, dwDialExtraPercent, dwDialExtraSampleSeconds, dwHangUpExtraPercent, and dwHangUpExtraSampleSeconds members. RAS uses these members for the Bandwidth Allocation Protocol (BAP). BAP is available only on Windows NT 5.0 or later versions.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RASADFunc, RasGetCountryInfo, RasSetEntryProperties, RasSetSubEntryProperties


RASENTRYDLG

The RASENTRYDLG structure is used in the RasEntryDlg function to specify addtional input and output parameters.

typedef struct tagRASENTRYDLG {
    IN  DWORD dwSize;
    IN  HWND  hwndOwner;
    IN  DWORD dwFlags;
    IN  LONG  xDlg;
    IN  LONG  yDlg;
    OUT WCHAR szEntry[ RAS_MaxEntryName + 1 ];
    OUT DWORD dwError;
    IN  DWORD reserved;
    IN  DWORD reserved2;
} RASENTRYDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasEntryDlg, set this member to sizeof(RASENTRYDLG) to indicate the version of the structure. If dwSize is not a valid size, RasEntryDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Identifies the window that owns the modal RasEntryDlg dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A set of bit flags that indicate the options enabled for the dialog box. This parameter can be a combination of the RASEDFLAG_PositionDlg flag and one of the other flags listed following to indicate whether the RasEntryDlg function is creating, copying, or editing a phone-book entry.
Value | Meaning
RASEDFLAG_PositionDlg | Causes RasEntryDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.
RASEDFLAG_NewEntry | Causes RasEntryDlg to display a wizard for creating a new phone-book entry.
RASEDFLAG_CloneEntry | Causes RasEntryDlg to create a new entry by copying the properties of an existing entry. The function displays a property sheet containing the properties associated with the phone-book entry specified by the lpszEntry parameter of RasEntryDlg. The user can edit the properties and specify a name for the new entry.
RASEDFLAG_NoRename | Causes RasEntryDlg to display a property sheet for editing the properties of the phone-book entry specified by the lpszEntry parameter of RasEntryDlg. The user can change the properties of the entry but not its name.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASEDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASEDFLAG_PositionDlg flag is set.
szEntry
On exit, szEntry is set to the name of the phone-book entry that was edited or created.
dwError
The RasEntryDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasEntryDlg


RASENTRYNAME

The RASENTRYNAME structure contains an entry name from a remote access phone book. The RasEnumEntries function returns an array of these structures.

typedef struct _RASENTRYNAME {
    DWORD  dwSize;
    TCHAR  szEntryName[RAS_MaxEntryName + 1];
}RASENTRYNAME;

Members

dwSize
Specifies the structure size, in bytes.
szEntryName
Specifies a string containing the name of a remote access phone-book entry.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasEnumEntries


RASIPADDR

The RASIPADDR structure contains an IP address. The RASENTRY structure uses this structure to specify the IP addresses of various servers associated with an entry in a RAS phone book.

typedef struct RASIPADDR {
    BYTE    a;
    BYTE    b;
    BYTE    c;
    BYTE    d;
} RASIPADDR;

Members

a, b, c, and d
These members specify the value of the corresponding location in the "a.b.c.d" IP address.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RASENTRY


RASMONITORDLG

The RASMONITORDLG structure is used in the RasMonitorDlg function to specify additional input and output parameters.

typedef struct tagRASMONITORDLG {
    IN  DWORD dwSize;
    IN  HWND  hwndOwner;
    IN  DWORD dwFlags;
    IN  DWORD dwStartPage;
    IN  LONG  xDlg;
    IN  LONG  yDlg;
    OUT DWORD dwError;
    IN  DWORD reserved;
    IN  DWORD reserved2;
} RASMONITORDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasMonitorDlg, set this member to sizeof(RASMONITORDLG) to indicate the version of the structure. If dwSize is not a valid size, RasMonitorDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Identifies the window that owns the modal RasMonitorDlg property sheet. This member can be any valid window handle, or it can be NULL if the property sheet has no owner.
dwFlags
A bit flag that indicates the options that are enabled for the property sheet. You can specify the following value.
Value | Meaning
RASMDFLAG_PositionDlg | Causes RasMonitorDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.

dwStartPage
A set of bit flags that indicate the initial page of the property sheet to display on top. You can specify one of the following values.
Value | Meaning
RASMDPAGE_Status | Display the Status page on top. This is the default.
RASMDPAGE_Summary | Display the Summary page on top.
RASMDPAGE_Preferences | Display the Preferences page on top.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the property sheet. This value is used only if the RASMDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the property sheet. This value is used only if the RASMDFLAG_PositionDlg flag is set.
dwError
The RasMonitorDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Import Library: Use rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasMonitorDlg


RASNOUSER

The RASNOUSER structure is used with the RasPBDlgFunc callback function to specify authentication credentials and other information. This structure enables dial-up networking operations that begin before a user has logged on. It is provided to support the WinLogon application, and is not typically used by other applications.

typedef struct tagRASNOUSER {
    IN  DWORD dwSize;
    IN  DWORD dwFlags;
    OUT DWORD dwTimeoutMs;
    OUT TCHAR szUserName[ UNLEN + 1 ];
    OUT TCHAR szPassword[ PWLEN + 1 ];
    OUT TCHAR szDomain[ DNLEN + 1 ];
} RASNOUSER;

Members

dwSize
Specifies the size of this structure, in bytes. This member indicates the version of the structure.
dwFlags
Reserved; must be zero.
dwTimeoutMs
Specifies the time, in milliseconds, before the RasPhonebookDlg dialog box closes and returns to the caller as if the user had pressed the Close button. This feature is required for code that displays a window during WinLogon. If the user leaves his or her terminal for some time, the dialog box closes and WinLogon reverts to the ctrl+alt+del prompt.
szUserName
Specifies a null-terminated string that contains the name of the user. This string is used to authenticate the user's right to access the remote access server.
szPassword
Specifies a null-terminated string that contains the user's password. This string is used to authenticate the user's right to access the remote access server.
szDomain
Specifies a null-terminated string that contains the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasPBDlgFunc, RasPhonebookDlg


RASPBDLG

The RASPBDLG structure is used with the RasPhonebookDlg function to specify additional input and output parameters.

typedef struct tagRASPBDLG {
    IN  DWORD         dwSize;
    IN  HWND          hwndOwner;
    IN  DWORD         dwFlags;
    IN  LONG          xDlg;
    IN  LONG          yDlg;
    IN  DWORD         dwCallbackId;
    IN  RASPBDLGFUNC  pCallback;
    OUT DWORD         dwError;
    IN  DWORD         reserved;
    IN  DWORD         reserved2;
} RASPBDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasPhonebookDlg, set this member to sizeof(RASPBDLG) to indicate the version of the structure. If dwSize is not a valid size, RasPhonebookDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Identifies the window that owns the modal RasPhonebookDlg dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A set of bit flags that indicate the options enabled for the dialog box. This parameter can be a combination of the following values.
Value | Meaning
RASPBDFLAG_PositionDlg | Causes RasPhonebookDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.
RASPBDFLAG_ForceCloseOnDial | Turns on the close-on-dial option, overriding the user's preference. This option is appropriate with features such as RAS AutoDial where the user's goal is to make a connection immediately.
RASPBDFLAG_NoUser | Causes the RasPBDlgFunc callback function specified by the pCallback member to receive a RASPBDEVENT_NoUser notification when the dialog box is starting up. This flag is for use in situations in which there is no logged-on user, as in the WinLogon application. Typically, applications should not use this flag.
RASPBDFLAG_UpdateDefaults | Causes the default window position to be saved on exit. This flag is used primarily by RASPHONE.EXE and should not be used by typical applications.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASPBDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASPBDFLAG_PositionDlg flag is set.
dwCallbackId
Specifies an application-defined value that is passed to the callback function specified by pCallback. You can use dwCallbackId to pass a pointer to application-specific context information.
pCallback
Pointer to a RasPBDlgFunc callback function that receives notifications of user activity while the dialog box is open. This member can be NULL if you do not want notifications.
dwError
The RasPhonebookDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasdlg.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasPBDlgFunc, RasPhonebookDlg


RASPPPIP

The RASPPPIP structure contains the result of a PPP Internet Protocol (IP) projection operation.

The RasGetProjectionInfo function returns a RASPPPIP data structure when its rasprojection parameter has the value RASP_PppIp.

typedef  struct  _RASPPPIP {
    DWORD    dwSize;
    DWORD    dwError;
    TCHAR    szIpAddress[ RAS_MaxIpAddress + 1 ];
} RASPPPIP;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to indicate the version of the RASPPPIP structure that you are using. For information about earlier versions of this structure, see the following Remarks section.
dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.
szIpAddress
Contains a zero-terminated string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, "11.101.237.71".
szServerIpAddress
Contains a null-terminated string that is the IP address of the remote PPP peer (that is, the server's IP address). This string is in "a.b.c.d" form. PPP does not require that servers provide this address, but Windows NT servers will consistently return the address anyway. Other PPP vendors may not provide the address. If the address is not available, this member returns an empty string, "".

Remarks

The szServerIpAddress member was added to the RASPPPIP structure beginning with Windows NT 3.51 and the initial release of Windows 95. Beginning with these systems, RasGetProjectionInfo will support both the current form of the structure and the old form without the szServerIpAddress member. Use the dwSize member to indicate which version you are using.

For earlier versions of Windows NT, RasGetProjectionInfo will return ERROR_INVALID_SIZE if dwSize specifies the current structure size. To retrieve PPP IP information from older systems, dwSize must specify the size of the old structure without the szServerIpAddress member.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetProjectionInfo, RASPROJECTION


RASPPPIPX

The RASPPPIPX structure contains the result of a PPP Internetwork Packet Exchange (IPX) projection operation.

The RasGetProjectionInfo function returns a RASPPPIPX data structure when its rasprojection parameter has the value RASP_PppIpx.

typedef  struct  _RASPPPIPX {
    DWORD    dwSize;
    DWORD    dwError;
    TCHAR    szIpxAddress[ RAS_MaxIpxAddress + 1 ];
} RASPPPIPX;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPIPX). The function can then determine the version of the RASPPPIPX data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.
dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.
szIpxAddress
Contains a zero-terminated string that is the client's IPX address on the RAS connection. This address string has the form net.node; for example, "1234ABCD.12AB34CD56EF".

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetProjectionInfo, RASPROJECTION


RASPPPNBF

The RASPPPNBF structure contains the result of a PPP NetBEUI Framer (NBF) projection operation.

The RasGetProjectionInfo function returns a RASPPPNBF data structure when its rasprojection parameter has the value RASP_PppNbf.

typedef  struct  _RASPPPNBF {
    DWORD    dwSize;
    DWORD    dwError;
    DWORD    dwNetBiosError;
    TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];
    TCHAR    szWorkstationName[ NETBIOS_NAME_LEN + 1 ];
    BYTE     bLana;
} RASPPPNBF;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPNBF). The function can then determine the version of the RASPPPNBF data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.
dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.
dwNetBiosError
If dwError has the value ERROR_SERVER_NOT_RESPONDING or ERROR_NETBIOS_ERROR, the dwNetBiosError field contains the NetBIOS error that occurred. For other values of dwError, this field contains zero.

Windows 95: This member is undefined.

szNetBiosError
If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.
szWorkStationName
Contains a zero-terminated string that is the local workstation's computer name. This unique computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a remote access connection.
bLana
Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetProjectionInfo, RASPROJECTION


RASSLIP

The RASSLIP structure contains the results of a the Serial Line Internet Protocol (SLIP) projection operation.

RASSLIP {
    DWORD dwSize;
    DWORD dwError;
    TCHAR szIpAddress[ RAS_MaxIpAddress + 1 ];
};

Members

dwSize
Specifies the size, in bytes, of the RASSLIP structure. Before calling the RasGetProjectionInfo function, set dwSize to sizeof(RASSLIP) to identify the version of the structure.
dwError
Indicates whether SLIP is configured. If dwError is zero, SLIP framing is configured. Otherwise, dwError is ERROR_PROTOCOL_NOT_CONFIGURED.
szIpAddress
A null-terminated string that contains the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, "11.101.237.71".

Remarks

If the RASENTRY structure for the phone-book entry used in a RAS connection specifies SLIP framing, you can call RasGetProjectionInfo with a RASPROJECTION of RASP_Slip to determine whether SLIP framing was successfully configured.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RASENTRY, RasGetProjectionInfo, RASPROJECTION


RASSUBENTRY

The RASSUBENTRY structure contains information about a subentry of a RAS phone-book entry. The RasSetSubEntryProperties and RasGetSubEntryProperties functions use this structure to set and retrieve the properties of a subentry.

typedef struct tagRASSUBENTRY {
    DWORD      dwSize;
    DWORD      dwfFlags;
    //
    // Device
    //
    TCHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
    TCHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
    //
    // Phone numbers
    //
    TCHAR      szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
    DWORD      dwAlternateOffset;
#if (WINVER >= 0x500)
    //
    // Port Name
    //
    TCHAR       szPortName[ RAS_MaxDeviceName + 1 ];
#endif
} RASSUBENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASSUBENTRY structure. Before calling RasSetSubEntryProperties or RasGetSubEntryProperties, set dwSize to sizeof(RASSUBENTRY) to identify the version of the structure.
dwfFlags
Currently unused. The RasSetSubEntryProperties function sets this member to zero. The RasGetSubEntryProperties function ignores this member.
szDeviceType
Specifies a null-terminated string indicating the RAS device type referenced by szDeviceName. This member can be one of the following string constants.
String | Description
RASDT_Modem | A modem accessed through a COM port.
RASDT_Isdn | An ISDN card with the corresponding NDISWAN driver installed.
RASDT_X25 | An X.25 card with the corresponding NDISWAN driver installed.
RASDT_Vpn | A virtual private network connection.
RASDT_Pad | A Packet Assembler/Disassembler

Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and RASDT_Pad device types are not supported on Windows 95.

Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, the RASDT_X25 and RASDT_Pad device types are not currently supported on Windows 98

szDeviceName
Specifies a null-terminated string containing the name of the TAPI device to use with this phone-book entry. To enumerate all available RAS-capable devices, use the RasEnumDevices function.
szLocalPhoneNumber
Specifies a null-terminated string containing a telephone number. The way RAS uses this string depends on whether the RASEO_UseCountryAndAreaCodes flag is set in the dwfOptions member of the RASENTRY structure for this phone-book entry. If the flag is set, RAS combines szLocalPhoneNumber with the country and area codes specified in the RASENTRY structure. If the flag is not set, RAS uses the szLocalPhoneNumber string as the entire phone number.
dwAlternateOffset
Specifies the offset, in bytes, from the beginning of the structure to a list of consecutive null-terminated strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that RAS dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect. The alternate phone number strings are ANSI or Unicode, depending on whether you use the ANSI or Unicode version of the structure.
szPortName
Specifies a null-terminated string containing the name of the port. The port name will depend on the RAS device type. For example, typical port names for a modem device would be "COM1" or "COM2.". For virtual private networks, the port name identifies the VPN connection.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in ras.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasGetSubEntryProperties, RasSetSubEntryProperties


SECURITY_MESSAGE

The SECURITY_MESSAGE structure is used with the RasSecurityDialogComplete function to indicate the results of a RAS security DLL authentication transaction.

typedef struct _SECURITY_MESSAGE {
    DWORD dwMsgId;
    HPORT hPort;
    DWORD dwError;
    CHAR  UserName[UNLEN+1];
    CHAR  Domain[DNLEN+1];
} SECURITY_MESSAGE, *PSECURITY_MESSAGE;

Members

dwMsgId
Indicates whether the RAS server should grant access to the remote user. This member can be one of the following values.
Value | Meaning
SECURITYMSG_SUCCESS | The security DLL successfully authenticated the remote user identified by the UserName member. The RAS server will proceed with its PPP authentication.
SECURITYMSG_FAILURE | The security DLL denied access to the remote user identified by the UserName member. The RAS server will hang up the call and record the failed authentication in the Windows NT event log.
SECURITYMSG_ERROR | An error occurred that prevented validation of the remote user. The RAS server will hang up the call and record the error in the Windows NT event log.

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
dwError
Specifies an error code. If dwMsgId is SECURITYMSG_ERROR, set dwError to one of the nonzero error codes defined in WINERROR.H or RASERROR.H. The RAS server records this error code in the Windows NT event log. If the dwMsgId member indicates success or failure, set dwError to zero.
UserName
Specifies the name of the remote user if dwMsgId is SECURITYMSG_SUCCESS or SECURITYMSG_FAILURE. This string can be empty if dwMsgId is SECURITYMSG_ERROR.
Domain
Specifies the name of the logon domain for the remote user if dwMsgId is SECURITYMSG_SUCCESS or SECURITYMSG_FAILURE. This string can be empty if dwMsgId is SECURITYMSG_ERROR.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasshost.h.

See Also

Remote Access Service Overview, RAS Server Administration Union, RasSecurityDialogBegin, RasSecurityDialogComplete


Remote Access Service Messages

Use the following message to implement Remote Access Service functionality:

WM_RASDIALEVENT


WM_RASDIALEVENT

The operating system sends a WM_RASDIALEVENT message to a window procedure when a change of state event occurs during a RAS connection process, and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

The two message parameters are equivalent to the parameters of the same names that are used with RasDialFunc and RasDialFunc1 callback functions.

WM_RASDIALEVENT
rasconnstate = (RASCONNSTATE) wParam; // connection state about to be entered
dwError = (DWORD) lParam;             // error that may have occurred

Parameters

rasconnstate
Value of wParam. Equivalent to the rasconnstate parameter of the RasDialFunc and RasDialFunc1 callback functions. Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
Value of lParam. Equivalent to the dwError parameter of the RasDialFunc and RasDialFunc1 callback functions. A nonzero value indicates the error that has occurred, or zero if no error has occurred.

RasDial sends this message with dwError set to zero upon entry to each connection state. If an error occurs within a state, the message is sent again for the state, this time with a nonzero dwError value.

Return Values

If an application processes this message, it should return TRUE.

QuickInfo

Windows NT: Requires version 3.5 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, Remote Access Service Messages, RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE


Remote Access Service Enumeration Types

Use the following enumeration types to implement Remote Access Service functionality:

RASCONNSTATE,
RASPROJECTION


RAS Server Administration Enumeration Types

For Windows NT version 4.0, use the following enumeration to implement RAS Server Administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMS_FORMAT


RASCONNSTATE

The RASCONNSTATE enumeration type contains values that specify the states that may occur during a RAS connection operation. If you use the RasDial function to establish a RAS connection, you can specify a window, or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive notification messages that report the current connection state. You can also use the RasGetConnectStatus function to get the connection state for a specified connection.

typedef enum _RASCONNSTATE {
    RASCS_OpenPort = 0,
    RASCS_PortOpened,
    RASCS_ConnectDevice,
    RASCS_DeviceConnected,
    RASCS_AllDevicesConnected,
    RASCS_Authenticate,
    RASCS_AuthNotify,
    RASCS_AuthRetry,
    RASCS_AuthCallback,
    RASCS_AuthChangePassword,
    RASCS_AuthProject,
    RASCS_AuthLinkSpeed,
    RASCS_AuthAck,
    RASCS_ReAuthenticate,
    RASCS_Authenticated,
    RASCS_PrepareForCallback,
    RASCS_WaitForModemReset,
    RASCS_WaitForCallback,
    RASCS_Projected,

#if (WINVER >= 0x400)
    RASCS_StartAuthentication,    // Windows 95 only
    RASCS_CallbackComplete,       // Windows 95 only
    RASCS_LogonNetwork,           // Windows 95 only
#endif
    RASCS_SubEntryConnected,
    RASCS_SubEntryDisconnected,

    RASCS_Interactive = RASCS_PAUSED,
    RASCS_RetryAuthentication,
    RASCS_CallbackSetByCaller,
    RASCS_PasswordExpired,

    RASCS_Connected = RASCS_DONE,
    RASCS_Disconnected
} RASCONNSTATE ;

The enumerator values are listed here in the general order in which the connection states occur. However, you should not write code that depends on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Enumerator Value | Meaning
RASCS_OpenPort | The communication port is about to be opened.
RASCS_PortOpened | The communication port has been opened successfully.
RASCS_ConnectDevice | A device is about to be connected. RasGetConnectStatus can be called to determine the name and type of the device being connected.
RASCS_DeviceConnected | A device has connected successfully. RasGetConnectStatus can be called to determine the name and type of the device being connected.
For a simple modem connection, RASCS_ConnectDevice and RASCS_DeviceConnected will be called only once. For a dial-up X.25 PAD connection, the pair will be called first for the modem, then for the PAD. If a preconnect switch is configured, the pair will be called for the switch before any other devices connect. Likewise, the pair will be called for a postconnect switch after any other devices connect.

Windows 95: Note that Windows 95 does not currently support multistage connections such as the X.25 PAD connection described earlier.
RASCS_AllDevicesConnected | All devices in the device chain have successfully connected. At this point, the physical link is established.
RASCS_Authenticate The authentication process is starting. Remote access does not allow the remote client to generate any traffic on the LAN until authentication has been successfully completed.

Remote access authentication on a Windows NT or Windows 95 server consists of:

  • Validating the user name/ password on the specified domain.
  • Projecting the client onto the LAN. This means that the remote access server does what is necessary to send and receive data on the LAN on behalf of the client. For example, the remote access server might need to add a NetBIOS name that corresponds to the client's computer name.
  • Call-back processing in which the client hangs up and the server calls back. (The user needs special permissions on the remote access server for this.)
  • Calculating the link speed. This is necessary to correctly set transport time-outs to match the relatively slow speed of the remote link.
RASCS_AuthNotify | An authentication event has occurred. If dwError is zero, this event will be immediately followed by one of the more specific authentication states following. If dwError is nonzero, authentication has failed, and the error value indicates why.
RASCS_AuthRetry | The client has requested another validation attempt with a new user name/password/domain. This state does not occur in Windows NT version 3.1.
RASCS_AuthCallback | The remote access server has requested a callback number. This occurs only if the user has "Set By Caller" callback privilege on the server.
RASCS_AuthChangePassword | The client has requested to change the password on the account. This state does not occur in Windows NT version 3.1.
RASCS_AuthProject | The projection phase is starting.
RASCS_AuthLinkSpeed | The link-speed calculation phase is starting.
RASCS_AuthAck | An authentication request is being acknowledged.
RASCS_ReAuthenticate | Reauthentication (after callback) is starting.
RASCS_Authenticated | The client has successfully completed authentication.
RASCS_PrepareForCallback | The line is about to disconnect in preparation for callback.
RASCS_WaitForModemReset | The client is delaying in order to give the modem time to reset itself in preparation for callback.
RASCS_WaitForCallback | The client is waiting for an incoming call from the remote access server.
RASCS_Projected | This state occurs after the RASCS_AuthProject state. It indicates that projection result information is available. You can access the projection result information by calling RasGetProjectionInfo.
RASCS_StartAuthentication | Windows 95 only: Indicates that user authentication is being initiated or retried.
RASCS_CallbackComplete | Windows 95 only: Indicates that the client has been called back and is about to resume authentication.
RASCS_LogonNetwork | Windows 95 only: Indicates that the client is logging on to the network.
RASCS_SubEntryConnected | When dialing a multilink phone-book entry, this state indicates that a subentry has been connected during the dialing process. The dwSubEntry parameter of a RasDialFunc2 callback function indicates the index of the subentry. When the final state of all subentries in the phone-book entry has been determined, the connection state is RASCS_Connected if one or more subentries have been connected successfully.
RASCS_SubEntryDisconnected | When dialing a multilink phone-book entry, this state indicates that a subentry has been disconnected during the dialing process. The dwSubEntry parameter of a RasDialFunc2 callback function indicates the index of the subentry.
RASCS_Interactive | This state corresponds to the terminal state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_RetryAuthentication | This state corresponds to the retry authentication state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_CallbackSetByCaller | This state corresponds to the callback state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_PasswordExpired | This state corresponds to the change password state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_Connected | Successful connection.
RASCS_Disconnected | Disconnection or failed connection.

Remarks

The connection process states are divided into three classes: running states, paused states, and terminal states.

An application can easily determine the class of a specific state by performing Boolean bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some examples:

fDoneState = (state & RASCS_DONE);
fPausedState = (state & RASCS_PAUSED);
fRunState = !(fDoneState || fPausedState);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, RAS Server Administration Enumeration Types, RasDial, RasGetConnectStatus, RasGetProjectionInfo, RASCONNSTATUS


RAS_PARAMS_FORMAT

The RAS_PARAMS_FORMAT enumeration type is used in the RAS_PARAMETERS structure to indicate the type of data associated with a media-specific key.

enum RAS_PARAMS_FORMAT {
    ParamNumber        = 0,
    ParamString        = 1
} ;

Enumerator Value | Meaning
ParamNumber | Indicates that the data associated with the key is a number.
ParamString | Indicates that the data associated with the key is a string.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

Remote Access Service Overview, RAS Server Administration Enumeration Types, RAS_PARAMETERS


RASPROJECTION

The RASPROJECTION enumeration type defines values that specify a particular authentication protocol or Point-to-Point Protocol (PPP) control protocol. An application passes a value of this type to the RasGetProjectionInfo function to specify the protocol of interest.

typedef enum _RASPROJECTION {
    RASP_Amb = 0x10000,
    RASP_PppNbf = 0x803F,
    RASP_PppIpx = 0x802B,
    RASP_PppIp = 0x8021
    RASP_Slip = 0x20000
} RASPROJECTION ;

Each of the RASPROJECTION enumerators has a corresponding data structure; the RasGetProjectionInfo function returns the specified information in a structure of that type.

Enumerator Value | Meaning
RASP_Amb | Specifies the Authentication Message Block (AMB) authentication protocol. AMB is a NetBIOS-based protocol used to authenticate with downlevel remote access servers ( all those prior to Windows NT 3.5). The corresponding data structure is a RASAMB.
RASP_PppNbf | Specifies the NetBEUI Framer (NBF) protocol. NBFCP is a PPP network control protocol used to negotiate the parameters necessary to ship NetBEUI packets on a WAN link. The corresponding data structure is a RASPPPNBF.
RASP_PppIpx | Specifies the Internetwork Packet Exchange (IPX) control protocol. IPXCP is a PPP network control protocol used to negotiate the parameters necessary to ship IPX packets on a WAN link. The corresponding data structure is a RASPPPIPX.
RASP_PppIp | Specifies the Internet Protocol (IP) control protocol. IPCP is a PPP network control protocol used to negotiate the parameters necessary to ship IP packets on a WAN link. The corresponding data structure is a RASPPPIP.
RASP_Slip | Specifies the Serial Line Internet Protocol (SLIP). SLIP is a framing protocol used primarily in UNIX environments.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ras.h.

See Also

Remote Access Service Overview, RAS Server Administration Enumeration Types, RasGetProjectionInfo, RASAMB, RASPPPIP, RASPPPIPX, RASPPPNBF


Simple Network Management Protocol (SNMP)

The Simple Network Management Protocol (SNMP) is the Internet standard protocol for exchanging management information between management console applications such as HP Openview, Novell NMS, IBM NetView, or Sun Net Manager, and managed entities. The managed entities can include hosts, routers, bridges, and hubs.


New SNMP Programming Elements

[This is preliminary documentation and subject to change.]

The Microsoft® SNMP service for Windows NT® 5.0 adds support for the following programming features and elements:

  • New SNMP extension agent functions
  • New SNMP utility functions

In addition, the SNMP service adds support for the following structure:

  • AsnCounter64

The SNMP service also introduces the following changes:

  • Modified SNMP variable types
  • Modified SNMP PDU request types

New SNMP Extension Agent Functions

The following new SNMP extension agent functions are available to SNMP extension agents that run on Windows NT 5.0 and later.

  • SnmpExtensionClose
  • SnmpExtensionQueryEx

New SNMP Utility Functions

The following new SNMP utility functions simplify manipulation of octet strings and AsnAny structures, and provide functionality that is useful during the development of SNMP applications.

  • SnmpSvcGetUptime
  • SnmpSvcSetLogLevel
  • SnmpSvcSetLogType
  • SnmpUtilAsnAnyCpy
  • SnmpUtilAsnAnyFree
  • SnmpUtilDbgPrint
  • SnmpUtilOctetsCmp
  • SnmpUtilOctetsCpy
  • SnmpUtilOctetsFree
  • SnmpUtilOctetsNCmp

Modified SNMP Variable Types

The definitions for some SNMP variable types have changed. The SNMP.H file maps old variable types to the corresponding new types.

You should use the new SNMP variable type when you develop manager applications that use the Microsoft SNMP Management API. The following table lists the old SNMP variable types with the corresponding new variable type.

Old Variable Type | New Variable Type
ASN_RFC1155_IPADDRESS | ASN_IPADDRESS
ASN_RFC1155_COUNTER | ASN_COUNTER32
ASN_RFC1155_GAUGE | ASN_GAUGE32
ASN_RFC1155_TIMETICKS | ASN_TIMETICKS
ASN_RFC1155_OPAQUE | ASN_OPAQUE
ASN_RFC1213_DISPSTRING | ASN_OCTETSTRING

Modified SNMP PDU Request Types

The definitions for some SNMP PDU types have changed. The SNMP.H file maps old PDU types to the corresponding new types.

You should use the new SNMP PDU type when you develop manager applications that use the Microsoft SNMP Management API. The following table lists the old SNMP PDU types with the corresponding new PDU type.

Old PDU Type | New PDU Type
ASN_RFC1157_GETREQUEST | SNMP_PDU_GET
ASN_RFC1157_GETNEXTREQUEST | SNMP_PDU_GETNEXT
ASN_RFC1157_GETRESPONSE | SNMP_PDU_RESPONSE
ASN_RFC1157_SETREQUEST | SNMP_PDU_SET
ASN_RFC1157_TRAP | SNMP_PDU_V1TRAP


About SNMP

SNMP uses a distributed architecture consisting of managers and agents. An agent is an SNMP application that responds to queries from SNMP manager applications. The SNMP agent is responsible for retrieving and updating local management information based on the requests of the SNMP manager. The agent also notifies registered managers when significant events or traps occur. A manager is an SNMP application that generates queries to SNMP agent applications and receives traps from SNMP agent applications.

On computers running Microsoft® Windows NT® the SNMP agent is implemented by the SNMP service (SNMP.EXE). The SNMP manager is typically a third-party SNMP management console application. The management console application does not need to run on the same host as the SNMP agent. To use the information the Microsoft SNMP service provides, you need at least one SNMP management console application. Windows NT includes libraries that support SNMP management console applications, but Windows NT does not include an SNMP management console application at this time.


How SNMP Works

The following steps outline how a third-party SNMP management console application returns information from the SNMP service:

  1. The SNMP management console application formulates an SNMP message based on input from the user. The message includes a protocol data unit (PDU) and authentication information. The management console application can use the Microsoft SNMP Management API library (MGMTAPI.DLL) or the Microsoft WinSNMP Manager API library (WSNMP32.DLL) to perform this step.
  2. The SNMP management console application sends the SNMP message to the SNMP service, using the SNMP service libraries.
  3. The SNMP service receives the request. It verifies the authentication information and the source IP address.
  4. The SNMP service selects the appropriate extension agent and requests that the agent retrieve the requested information.
  5. The SNMP service sends the response to the SNMP management console application.


The SNMP Management Information Base (MIB)

A Management Information Base (MIB) describes a set of managed objects. An SNMP management console application can manipulate the objects on a specific computer if the SNMP service has an extension agent DLL that supports the MIB.

Each managed object in a MIB has a unique identifier. The identifier includes the object's type (such as counter, string, gauge, or address), the object's access level (such as read or read/write), size restrictions, and range information.

The following table lists the MIBs that ship with Windows NT. They are installed with the SNMP service.

MIB | Description
ACS.MIB | Microsoft-defined MIB for the ACS service
DHCP.MIB | Microsoft-defined MIB for the DHCP service
FTP.MIB | Microsoft-defined MIB for the FTP service
GOPHERD.MIB | Microsoft-defined MIB for the Gopher service
HOSTMIB.MIB | Host Resources MIB
HTTP.MIB | Microsoft-defined MIB for the HTTP service
INETSRV.MIB | Microsoft-defined MIB for IIS components
IPFORWD.MIB | IP Forwarding MIB
LMMIB2.MIB | LAN Manager MIB-II
MIB_II.MIB | MIB-II
MIPX.MIB | Microsoft-defined MIB for the IPX Protocol
MRIPSAP.MIB | Microsoft-defined MIB for the RIP routing protocol
MSFT.MIB | MIB that defines Microsoft's enterprise OID
MSIPBTP.MIB | Microsoft-defined MIB for the BootP service
MSIPRIP2.MIB | Microsoft-defined MIB for the RIP2 routing protocol
NIPX.MIB | Novell-defined MIB for the IPX Protocol
SMI.MIB | MIB that defines SMIv1 information
WFOSPF.MIB | WellFleet-defined MIB for the OSPF routing protocol
WINS.MIB | Microsoft-defined MIB for the WINS service

The extension agent DLLs for MIB-II, LAN Manager MIB-II, and the Host Resources MIB are installed with the SNMP service. The extension agent DLLs for the other MIBs are installed when their respective services are installed. At service startup time, the SNMP service loads all of the extension agent DLLs that are listed in the Windows NT registry.

Users can add other extension agent DLLs that implement additional MIBs. To do this, they must add a registry entry for the new DLL under the SNMP service. They must also register the new MIB with the SNMP management console application. For more information, see the documentation included with your management console application.


MIB Name Tree

The name space for MIB object identifiers is hierarchical. It is structured so that each manageable object can be assigned a globally unique name.

Authority for parts of the name space is assigned to individual organizations. This allows organizations to assign names without consulting an Internet authority for each assignment. For example, the name space assigned to Microsoft is 1.3.6.1.4.1.311, which is defined in MSFT.MIB. Microsoft has the authority to assign names to objects anywhere below that name space.

The object identifier in the hierarchy is written as a sequence of subidentifiers beginning at the root and ending at the object. Subidentifiers are separated with a period.


Relevant RFCs

TCP/IP standards are defined in Requests for Comments (RFCs), which are published by the Internet Engineering Task Force (IETF). The following table lists the RFCs that are relevant to SNMP.

RFC number | Title
1155 | "Structure and Identification of Management Information for TCP/IP-based Internets." It defines SMI.MIB.
1157 | "A Simple Network Management Protocol (SNMP)." It defines SNMP itself.
1213 | "Management Information Base for Network Management of TCP/IP-based internets: MIB-II." It defines MIB_II.MIB.
1901 | "Introduction to Community-based SNMPv2"
1902 | "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1903 | "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1904 | "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1905 | "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1906 | "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1907 | "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1908 | "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework"
2089 | "V2ToV1 Mapping SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent"


Windows NT Files for SNMP

The following table describes the files that relate to the SNMP service.

Filename | Description
ACSMIB.DLL | Extension agent DLL that implements the Microsoft-defined ACS MIB. Installed only on ACS servers, and not available on Windows NT 3.1 or 4.0.
DHCPMIB.DLL | Extension agent DLL that implements the Microsoft-defined DHCP MIB. Installed only on DHCP servers, and not available on Windows NT 3.1.
HOSTMIB.DLL | Extension agent DLL that implements the Host Resources MIB.
INETMIB1.DLL | Extension agent DLL that implements MIB-II.
LMMIB2.DLL | Extension agent DLL that implements LAN Manager MIB-II.
MGMTAPI.DLL | Microsoft SNMP Management API library.
MIB.BIN | Compiled MIB information used by MGMTAPI.DLL.
SNMP.EXE | SNMP service. This is the master agent that receives SNMP requests and delivers them to the appropriate extension agent DLL.
SNMPAPI.DLL | SNMP utilities DLL used by SNMP extension agent DLLs and manager applications.
SNMPCFG.EXE | SNMP configuration utility.
SNMPSFX.DLL | SNMP subagent framework DLL. This is a helper library for writing extension agent DLLs.
SNMPTRAP.EXE | SNMP trap service. Receives SNMP traps and forwards them to SNMP manager applications using MGMTAPI.DLL and WinSNMP.DLL.
WINSMIB.DLL | Extension agent DLL that implements the Microsoft-defined WINS MIB. Installed only on WINS servers, and not available on Windows NT 3.1.
WSNMP32.DLL | Microsoft WinSNMP Manager API version 1.1a library.


SNMP Utilities

The following table summarizes the SNMP utilities and files that are available on the Microsoft Windows Resource Kit.

Filename | Description
MIBCC.EXE | SNMP MIB Compiler
SNMPUTIL.EXE | A sample SNMP manager console application


Configuring the SNMP Service

On occasion, you may need to reconfigure SNMP. In these instances, you need to know community names in your network, the trap destination for each community, and IP addresses or computer names for SNMP management hosts before you use or reconfigure SNMP services. The following topics contain information relevant to configuring the SNMP service:

  • Community names
  • Host names and IP addresses
  • Configuring SNMP security
  • Configuring SNMP agent information


Community Names

A community name identifies a collection of SNMP managers and agents. The use of a community name provides primitive security and context checking for both agents and managers that receive requests and initiate trap operations. An agent won't accept a request from a manager outside the community.


Host Names and IP Addresses

If the Windows NT computer does not have access to a WINS server, the SNMP service uses the HOSTS file to resolve host names to IP addresses. The HOST file is merely a text file listing explicit host names and IP addresses. If you use host names, be sure to add all host name and IP address mappings of the participating systems.


Configuring SNMP Security

SNMP security allows you to specify the communities and hosts from which a computer will accept requests. It also allows you to specify whether to send an authentication trap when an unauthorized community or host requests information.


Configuring SNMP Agent Information

SNMP agent information allows you to specify comments about the user and the physical location of the computer and to indicate the types of service to report. The types of service that can be reported are based on the computer's configuration.


SNMP Reference

This section provides the SNMP functions and structures. These elements support the development of SNMP agent applications and SNMP manager applications for Windows NT®.


SNMP Functions

The SNMP functions fall into the following three functional groupings:

  • SNMP Extension Agent API functions
  • SNMP Management API functions
  • SNMP Utility API functions

SNMP Extension Agent API Functions

The SNMP Extension Agent API functions define the interface between the SNMP service and the third-party SNMP extension agent DLLs. Applications use these functions to resolve the variable bindings specified by incoming SNMP PDUs.

SnmpExtensionClose
SnmpExtensionInit
SnmpExtensionInitEx
SnmpExtensionQuery
SnmpExtensionQueryEx
SnmpExtensionTrap

SNMP Management API Functions

The SNMP Management API functions define the interface between third-party SNMP manager applications and the management function dynamic-link library MGMTAPI.DLL. The DLL works in conjunction with the SNMP trap service (SNMPTRAP.EXE), and can interact with one or more third-party SNMP manager applications. Third-party manager applications can use the management functions to perform SNMP manager operations.

SnmpMgrClose
SnmpMgrGetTrap
SnmpMgrOidToStr
SnmpMgrOpen
SnmpMgrRequest
SnmpMgrStrToOid
SnmpMgrTrapListen

SNMP Utility API Functions

The SNMP Utility API functions simplify manipulation of SNMP data structures and provide functionality that is useful during the development of SNMP applications.

SnmpSvcGetUptime
SnmpSvcSetLogLevel
SnmpSvcSetLogType
SnmpUtilAsnAnyCpy
SnmpUtilAsnAnyFree
SnmpUtilDbgPrint
SnmpUtilMemAlloc
SnmpUtilMemFree
SnmpUtilMemReAlloc
SnmpUtilOctetsCmp
SnmpUtilOctetsCpy
SnmpUtilOctetsFree
SnmpUtilOctetsNCmp
SnmpUtilOidAppend
SnmpUtilOidCmp
SnmpUtilOidCpy
SnmpUtilOidFree
SnmpUtilOidNCmp
SnmpUtilPrintAsnAny
SnmpUtilVarBindCpy
SnmpUtilVarBindListCpy
SnmpUtilVarBindFree
SnmpUtilVarBindListFree


SnmpExtensionClose

[This is preliminary documentation and subject to change.]

The Microsoft SNMP service calls the SnmpExtensionClose function to request that the SNMP extension agent deallocate resources and terminate operations. This function is an element of the SNMP Extension Agent API.

Note The SNMP service calls the SnmpExtensionClose function only if the extension agent is running on Windows NT 5.0 and later. For more information, see the following Remarks section.

VOID SnmpExtensionClose(
);

Parameters

This function has no parameters.

Return Values

None.

Remarks

An SNMP extension agent that runs on Windows NT 3.51 or 4.0 can also export the SnmpExtensionClose function. Because the SNMP service does not call this function under these conditions, the extension agent must call SnmpExtensionClose manually. It should do this when the SNMP service calls the extension agent's DllMain function with the value DLL_PROCESS_DETACH. The extension agent must clean up allocated resources and terminate services at this time.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionInitEx


SnmpExtensionInit

The Microsoft SNMP service calls the SnmpExtensionInit function to initialize the SNMP extension agent DLL. This function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionInit(
  DWORD dwUptimeReference,                    // see NOTE below
  HANDLE *phSubagentTrapEvent,                // trap event handle
  AsnObjectIdentifier *pFirstSupportedRegion  // first MIB subtree
);

Parameters

dwUptimeReference
[in] Specifies a time-zero reference for the extension agent.

Note Extension agents should ignore this parameter. The SNMP extension agent DLL should use the SnmpSvcGetUptime function to retrieve the number of centiseconds the SNMP service has been running. For more information, see the following Remarks section.

phSubagentTrapEvent
[out] Pointer to an event handle the extension agent passes back to the SNMP service. This handle is used to notify the service that the extension agent has one or more traps to send. For additional information about allocating and deallocating the event handle, see the following Remarks section.
pFirstSupportedRegion
[out] Pointer to an AsnObjectIdentifier structure to receive the first MIB subtree that the extension agent supports. For additional information about allocating and deallocating resources for this structure, see the following Remarks section.

The extension agent can register additional MIB subtrees by implementing the SnmpExtensionInitEx entry point function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Extension agents should ignore the dwUptimeReference parameter. Instead, they should call the SnmpSvcGetUptime function to retrieve the number of centiseconds that the Microsoft SNMP service has been running. Because the dwUptimeReference parameter stores the elapsed time as a DWORD value in milliseconds, the time can wrap to zero and reflect an inaccurate time interval.

The extension agent notifies the SNMP service that it needs to send one or more traps by setting the event handle passed back in the phSubagentTrapEvent parameter to the signaled state. After this event has been signaled, the SNMP service repeatedly calls the extension agent's SnmpExtensionTrap entry point until the function returns a value of FALSE. This indicates that the extension agent has no more traps to send. If the extension agent does not generate traps, the phSubagentTrapEvent parameter should return a value of NULL.

The SNMP extension agent must allocate and deallocate resources for the trap event handle. When the SNMP service calls the SnmpExtensionInit function, the extension agent must call the CreateEvent function to allocate the event handle. The extension agent passes the handle to the SNMP service in the phSubagentTrapEvent parameter. When the SNMP service calls the SnmpExtensionClose function, the extension agent must deallocate resources for the trap event handle.

The SNMP service makes a copy of the AsnObjectIdentifier structure the extension agent returns in the pFirstSupportedRegion parameter. The extension agent must allocate and deallocate the resources associated with the original structure. It can do this when the SNMP service calls the SnmpExtensionClose function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnObjectIdentifier, CreateEvent, SnmpExtensionTrap, SnmpSvcGetUptime, SnmpExtensionClose


SnmpExtensionInitEx

The Microsoft SNMP service calls the SnmpExtensionInitEx function to identify any additional management information base (MIB) subtrees the SNMP extension agent supports. This function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionInitEx(
  AsnObjectIdentifier *pNextSupportedRegion  // next MIB subtree
);

Parameters

pNextSupportedRegion
[out] Pointer to an AsnObjectIdentifier structure to receive the next MIB subtree that the extension agent supports.

Return Values

If the pNextSupportedRegion parameter has been initialized with an additional MIB subtree, the return value is TRUE.

If there are no more MIB subtrees to register, the return value is FALSE.

Remarks

The SNMP service repeatedly calls the SnmpExtensionInitEx function entry point so the extension agent can register support for additional MIB subtrees.

The SNMP service makes a copy of the AsnObjectIdentifier structure the extension agent returns in the pNextSupportedRegion parameter. The extension agent must allocate and deallocate the resources associated with the original structure. It can do this when the SNMP service calls the SnmpExtensionClose function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionClose, AsnObjectIdentifier


SnmpExtensionQuery

The Microsoft SNMP service calls the SnmpExtensionQuery function to resolve SNMP requests that contain variables within one or more of the SNMP extension agent's registered MIB subtrees. This function is an element of the SNMP Extension Agent API.

Note The extension agent must export the SnmpExtensionQuery function if the extension agent runs on Windows NT 3.51 or 4.0. However, it is recommended that you use the SnmpExtensionQueryEx function, which supports SNMP version 2C (SNMPv2C) data types and multiphase SNMP SET operations.

BOOL  SnmpExtensionQuery(
  BYTE bPduType,                  // SNMPv1 PDU request type
  SnmpVarBindList *pVarBindList,  // pointer to variable bindings
  AsnInteger32 *pErrorStatus,     // pointer to SNMPv1 error status
  AsnInteger32 *pErrorIndex       // pointer to the error index
);

Parameters

bPduType
[in] Specifies the SNMP version 1 (SNMPv1) PDU request type. This parameter can be one of the following values.
Value | Meaning
SNMP_PDU_GET | Retrieve the value or values of the specified variables.
SNMP_PDU_GETNEXT | Retrieve the value or values of the lexicographic successor of the specified variable.
SNMP_PDU_SET | Write a value within a specific variable.

Note that PDU request types have been renamed. For additional information, see Modified SNMP PDU Request Types.

pVarBindList
[in/out] Pointer to the variable bindings list.
pErrorStatus
[out] Pointer to a variable in which the error status result will be returned. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_ERRORSTATUS_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERRORSTATUS_TOOBIG | The agent could not place the results of the requested operation into a single SNMP message.
SNMP_ERRORSTATUS_NOSUCHNAME | The requested operation identified an unknown variable.
SNMP_ERRORSTATUS_BADVALUE | The requested operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERRORSTATUS_READONLY | The requested operation tried to change a variable that was not allowed to change according to the community profile of the variable.
SNMP_ERRORSTATUS_GENERR | An error other than one of those listed here occurred during the requested operation.

pErrorIndex
[out] Pointer to a variable in which the error index result will be returned.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When the SNMP service receives an SNMP PDU request, it calls the SnmpExtensionQuery function to process the request. The extension agent must follow the rules in RFC 1157 to either resolve the variable bindings or generate an error.

If the extension agent cannot resolve the variable bindings on a Get Next request, it must change the name field of the SnmpVarBind structure to the value of the object identifier immediately following that of the currently supported MIB subtree view. For example, if the extension agent supports view ".1.3.6.1.4.1.77.1", a Get Next request on ".1.3.6.1.4.1.77.1.5.1" would result in a modified name field of ".1.3.6.1.4.1.77.2". This signals the SNMP service to continue the attempt to resolve the variable bindings with other extension agents.

It is important to note that the SNMP service and the extension agent may need to exchange dynamically allocated memory during a call to the SnmpExtensionQuery function. The service dynamically allocates the object identifier in each SnmpVarBind structure it passes to the extension agent. However, the extension agent must release this memory in order to replace the object identifier when it processes a Get Next request. The extension agent allocates dynamic memory for variable-length object types. The SNMP service releases this memory after the object is placed in the response PDU.

In order to avoid heap corruption and memory leaks, both the SNMP service and the extension agent must use memory allocation routines that resolve to the same heap. The extension agent must use the SnmpUtilMemAlloc function to allocate memory that it passes to the SNMP service. It must use the SnmpUtilMemFree function to release the memory the service passes back to the extension agent. These functions are located in the utility dynamic-link library SNMPAPI.DLL.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpExtensionInit, SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpExtensionQueryEx

[This is preliminary documentation and subject to change.]

The Microsoft SNMP service calls the SnmpExtensionQueryEx function to process SNMP requests that specify variables in one or more MIB subtrees registered by SNMP extension agents. This function is an element of the SNMP Extension Agent API.

Note It is recommended that you use the SnmpExtensionQueryEx function, which supports SNMP version 2C (SNMPv2C) data types and multiphase SNMP SET operations. However, the extension agent must also export the SnmpExtensionQuery function if the extension agent runs on Windows NT 3.51 or 4.0. The SNMP service does not call the SnmpExtensionQuery function if the extension agent exports the SnmpExtensionQueryEx function.

BOOL SnmpExtensionQueryEx(
  DWORD dwRequestType,           // extension agent request type
  DWORD dwTransactionId,         // identifier of the incoming PDU
  SnmpVarBindList *pVarBindList, // pointer to variable binding list
  AsnOctetString *pContextInfo,  // pointer to context information
  AsnInteger32 *pErrorStatus,    // pointer to SNMPv2 error status
  AsnInteger32 *pErrorIndex      // pointer to the error index
);

Parameters

dwRequestType
Specifies the type of operation that the SNMP service is requesting the extension agent to perform. This parameter can be one of the following values.
Value | Meaning
SNMP_EXTENSION_GET | Retrieve the value or values of the specified variables.
SNMP_EXTENSION_GET_NEXT | Retrieve the value or values of the lexicographic successor of the specified variables.
SNMP_EXTENSION_SET_TEST | Validate the values of the specified variables. This operation maximizes the probability of a successful write during the COMMIT request.
SNMP_EXTENSION_SET_COMMIT | Write the new values to the specified variables.
SNMP_EXTENSION_SET_UNDO | Reset the values of the specified variables to their values before the COMMIT request.
SNMP_EXTENSION_SET_
CLEANUP 		Release the resources allocated in previous requests and operations.

For additional information about the SET request types, that is, those that begin with SNMP_EXTENSION_SET_, see the following Remarks section.

dwTransactionId
Specifies a DWORD variable that is the unique identifier of the incoming SNMP request PDU. The extension agent can use this value to correlate multiple calls by the SNMP service that involve the same PDU.
pVarBindList
Pointer to the variable binding list containing the variables of interest.
pContextInfo
Pointer to an octet string that contains user-defined context information.

The extension agent can use this parameter to store context information used during multiphase SNMP SET operations. The extension agent must release resources associated with this parameter during the CLEANUP request. The SNMP service does not release any resources associated with this parameter. For additional information, see the following Remarks section.

pErrorStatus
Pointer to a variable to receive the error status result. This parameter can be one of the following values defined by SNMPv2C.
Error Code | Meaning
SNMP_ERROR_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERROR_TOOBIG | The agent could not place the results of the requested SNMP operation into a single SNMP message.
SNMP_ERROR_NOSUCHNAME | The requested SNMP operation identified an unknown variable.
SNMP_ERROR_BADVALUE | The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERROR_READONLY | The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
SNMP_ERROR_GENERR | An error other than one of those listed here occurred during the requested SNMP operation.
SNMP_ERROR_NOACCESS | The specified SNMP variable is not accessible.
SNMP_ERROR_WRONGTYPE | The value specifies a type that is inconsistent with the type required for the variable.
SNMP_ERROR_WRONGLENGTH | The value specifies a length that is inconsistent with the length required for the variable.
SNMP_ERROR_WRONGENCODING | The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
SNMP_ERROR_WRONGVALUE | The value cannot be assigned to the variable.
SNMP_ERROR_NOCREATION | The variable does not exist, and the agent cannot create it.
SNMP_ERROR_
INCONSISTENTVALUE 		The value is inconsistent with values of other managed objects.
SNMP_ERROR_
RESOURCEUNAVAILABLE 		Assigning the value to the variable requires allocation of resources that are currently unavailable.
SNMP_ERROR_COMMITFAILED | No validation errors occurred, but no variables were updated.
SNMP_ERROR_UNDOFAILED | No validation errors occurred. Some variables were updated because it was not possible to undo their assignment.
SNMP_ERROR_
AUTHORIZATIONERROR 		An authorization error occurred.
SNMP_ERROR_NOTWRITABLE | The variable exists but the agent cannot modify it.
SNMP_ERROR_
INCONSISTENTNAME 		The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

pErrorIndex
Pointer to a variable to receive the error index result.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The SNMP service calls the SnmpExtensionQueryEx function multiple times to process an incoming SNMP SET request. The service can call SnmpExtensionQueryEx during the TEST request phase, the COMMIT request phase, the UNDO request phase, and the CLEANUP request phase.

TEST request

The SNMP service processes an SNMP SET request type by first calling the SnmpExtensionQueryEx function with a dwRequestType of SNMP_EXTENSION_SET_TEST. The service calls each extension agent responsible for the variable bindings in the request. Each extension agent must validate the variables in the variable binding list. They can optionally store any context information required for the following requests in the variable pointed to by the pContextInfo parameter.

If the TEST request fails, the service initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the TEST request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

COMMIT request

If all extension agents return TRUE to the TEST request, the SNMP service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_COMMIT dwRequestType. The service returns to the extension agent context information that the extension agent passed to the service. This is the context information the extension agent passed in the pContextInfo parameter during the TEST request. The extension agent can use the context information to update the values of the specified variables in an instrumentation-specific manner.

If the extension agent supports rollback processing, it can update the context information in the pContextInfo parameter at this time. The SNMP service passes the information back to the extension agent during the UNDO request.

If all extension agents return TRUE to the COMMIT request, the service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

If any extension agent fails the COMMIT request, the service also initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the COMMIT request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

CLEANUP request

The service returns to the extension agent the context information passed in the pContextInfo parameter during the TEST or COMMIT request. The extension agent must release the resources associated with the parameter at this time.

UNDO request

If any extension agent returns FALSE to the COMMIT request, the SNMP service terminates the COMMIT request. The service calls each extension agent that returned TRUE to the COMMIT request with a dwRequestType of SNMP_EXTENSION_SET_UNDO. This signals the extension agents that the COMMIT request failed, and they must initiate rollback processing.

The extension agents must attempt to reset the values of the variables of interest, back to the values they were before the COMMIT request failed. To do this, the extension agents use the context information returned in the pContextInfo parameter during the COMMIT request.

If any extension agent returns FALSE to the UNDO request, the entire SET operation fails with the error code SNMP_ERRORSTATUS_UNDOFAILED. If all extension agents return TRUE to the UNDO request, the SNMP SET operation fails with the error code set by the extension agent that failed the COMMIT request.

After the UNDO request the service always calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionQuery, AsnOctetString, SnmpVarBindList


SnmpExtensionTrap

The Microsoft SNMP service calls the SnmpExtensionTrap function to retrieve information the service needs to generate traps for the SNMP extension agent. The service calls this function only after the extension agent sets the trap event handle to the signaled state during a call to the SnmpExtensionInit function. The SnmpExtensionTrap function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionTrap(
  AsnObjectIdentifier *pEnterpriseOid,  // generating enterprise
  AsnInteger32 *pGenericTrapId,         // generating trap type
  AsnInteger32 *pSpecificTrapId,        // enterprise-specific type
  AsnTimeticks *pTimeStamp,             // time stamp
  SnmpVarBindList *pVarBindList         // variable bindings
);

Parameters

pEnterpriseOid
[out] Pointer to an AsnObjectIdentifier structure to receive the object identifier of the enterprise that generated the trap. The SNMP service does not free the memory for this variable.
pGenericTrapId
[out] Pointer to a variable to receive an indication of the generic trap. This parameter can be one of the following values.
Value | Meaning
SNMP_GENERICTRAP_COLDSTART | The agent is initializing protocol entities on the managed mode. It may alter objects in its view.
SNMP_GENERICTRAP_WARMSTART | The agent is re-initializing itself but will not alter objects within its view.
SNMP_GENERICTRAP_LINKDOWN | An attached interface has changed from the up state to the down state. The first variable identifies the interface.
SNMP_GENERICTRAP_LINKUP | An attached interface has changed from the down state to the up state. The first variable identifies the interface.
SNMP_GENERICTRAP_AUTHFAILURE | An SNMP entity has sent an SNMP message, but has falsely claimed to belong to a known community.
SNMP_GENERICTRAP_EGPNEIGHLOSS | An EGP peer has changed to the down state. The first variable identifies the IP address of the EGP peer.
SNMP_GENERICTRAP_ENTERSPECIFIC | Signals an extraordinary event that is identified in the pSpecificTrapId parameter.

pSpecificTrapId
[out] Pointer to a variable to receive an indication of the specific trap generated.
pTimeStamp
[out] Pointer to a variable to receive the time stamp. It is recommended that you initialize this parameter with the value returned by a call to the SnmpSvcGetUptime function.
pVarBindList
[out] Pointer to the variable bindings list. The extension agent must allocate the memory for this parameter. The SNMP service frees the memory with a call to the SnmpUtilVarBindListFree function.

Return Values

If the SnmpExtensionTrap function returns a trap, the return value is TRUE. The SNMP service repeatedly calls the function until it returns a value of FALSE. For additional information, see the following Remarks section.

Remarks

The SNMP service repeatedly calls the SnmpExtensionTrap function when the phSubagentTrapEvent event handle is set to the signaled state. This handle is passed back during the call to the SnmpExtensionInit entry point function. The SnmpExtensionTrap function must return TRUE to indicate that the parameters contain valid data for a single trap. The function must return FALSE to indicate that the parameters do not represent valid trap data, and to stop the service's repeated calls.

Note that after the SNMP service sends a trap, it frees the memory associated with the variable binding list.

It is important to note that earlier documentation stated that the extension agent should dynamically allocate memory for the enterprise object identifier because the SNMP service would attempt to release the memory after sending a trap. The service will not release the memory associated with the enterprise object identifier. It is recommended that you return a pointer to a static AsnObjectIdentifier structure instead.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SetEvent, SnmpUtilMemAlloc, SnmpUtilVarBindListFree, SnmpVarBindList, SnmpSvcGetUptime, SnmpExtensionInit


SnmpMgrClose

The SnmpMgrClose function closes communications sockets and data structures associated with the specified session. This function is an element of the SNMP Management API.

BOOL SnmpMgrClose(
  LPSNMP_MGR_SESSION session  // SNMP session pointer
);

Parameters

session
[in] Pointer to an internal structure that specifies the session to close.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function may return Windows Sockets error codes.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOpen, SnmpMgrRequest


SnmpMgrGetTrap

The SnmpMgrGetTrap function returns outstanding trap data that the caller has not received if trap reception is enabled. This function is an element of the SNMP Management API.

BOOL SnmpMgrGetTrap(
  AsnObjectIdentifier *enterprise,   // generating enterprise
  AsnNetworkAddress *IPAddress,      // generating IP address
  AsnInteger *genericTrap,           // generic trap type
  AsnInteger *specificTrap,          // enterprise-specific type
  AsnTimeticks *timeStamp,           // time stamp
  SnmpVarBindList *variableBindings  // variable bindings
);

Parameters

enterprise
[out] Pointer to an object identifier to receive the enterprise that generated the SNMP trap.
IPAddress
[out] Pointer to a variable to receive the IP address of the enterprise that generated the SNMP trap.
genericTrap
[out] Pointer to a variable to receive an indicator of the generic trap. This parameter can be one of the following values.
Value | Meaning
SNMP_GENERICTRAP_COLDSTART | The agent is initializing protocol entities on the managed mode. It may alter objects in its view.
SNMP_GENERICTRAP_WARMSTART | The agent is re-initializing itself but it will not alter objects in its view.
SNMP_GENERICTRAP_LINKDOWN | An attached interface has changed from the up state to the down state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_LINKUP | An attached interface has changed from the down state to the up state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_AUTHFAILURE | An SNMP entity has sent an SNMP message, but it has falsely claimed to belong to a known community.
SNMP_GENERICTRAP_EGPNEIGHLOSS | An EGP peer has changed to the down state. The first variable in the variable bindings list identifies the IP address of the EGP peer.
SNMP_GENERICTRAP_ENTERSPECIFIC | An extraordinary event has occurred and it is identified in the specificTrap parameter with an enterprise-specific value.

specificTrap
[out] Pointer to a variable to receive an indication of the specific trap generated.
timeStamp
[out] Pointer to a variable to receive the time stamp.
variableBindings
[out] Pointer to an SnmpVarBindList structure to receive the variable bindings list.

Return Values

If the function returns a trap, the return value is nonzero.

You should call the SnmpMgrGetTrap function repeatedly until GetLastError returns zero. GetLastError may also return the following error codes.

Error Code | Meaning
SNMP_MGMTAPI_TRAP_ERRORS | Indicates errors were encountered; traps are not accessible.
SNMP_MGMTAPI_NOTRAPS | Indicates no traps are available.
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error.

Remarks

The application must always call the SnmpMgrTrapListen function before calling the SnmpMgrGetTrap function. This is because the event handle pointed to by the phTrapAvailable parameter of the SnmpMgrTrapListen function enables the event-driven acquisition of SNMP traps. The SNMP Management API signals an application's event when the SNMP Trap Service delivers a trap.

The application can also poll the SnmpMgrGetTrap function for traps at regular intervals. In this case, the application should repeatedly call SnmpMgrGetTrap until the function returns zero.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrTrapListen, SnmpVarBindList


SnmpMgrOidToStr

The SnmpMgrOidToStr function converts an internal object identifier structure to its string representation. This function is an element of the SNMP Management API.

BOOL SnmpMgrOidToStr(
  AsnObjectIdentifier *oid,
                  // object identifier to convert
  LPSTR *string   // string object identifier representation
);

Parameters

oid
[in] Pointer to an object identifier variable to convert.
string
[out] Pointer to a null-terminated string to receive the converted value.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function may return Windows Sockets error codes.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrStrToOid


SnmpMgrOpen

The SnmpMgrOpen function initializes communications sockets and data structures, allowing communications with the specified SNMP agent. This function is an element of the SNMP Management API.

LPSNMP_MGR_SESSION SnmpMgrOpen(
  LPSTR lpAgentAddress,    // name and address of target SNMP agent
  LPSTR lpAgentCommunity,  // community for target SNMP agent
  INT nTimeOut,            // communication time-out in milliseconds
  INT nRetries             // communication time-out or retry count
);

Parameters

lpAgentAddress
[in] Pointer to a null-terminated string specifying either a dotted-decimal IP address or a host name that can be resolved to an IP address, an IPX address (in 8.12 notation), or an ethernet address.
lpAgentCommunity
[in] Pointer to a null-terminated string specifying the SNMP community name used when communicating with the agent specified in the lpAgentAddress parameter.
nTimeOut
[in] Specifies the communications time-out in milliseconds.
nRetries
[in] Specifies the communications retry count. The time-out specified in the nTimeOut parameter is doubled each time a retry attempt is transmitted.

Return Values

If the function succeeds, the return value is a pointer to an LPSNMP_MGR_SESSION structure. This structure is used internally and the programmer should not alter it.

If the function fails, the return value is NULL. To get extended error information, call GetLastError. GetLastError may return the SNMP_MEM_ALLOC_ERROR error code, which indicates a memory allocation error.

This function may also return Windows Sockets error codes.

The name and address of the SNMP target, or the string pointed to by the lpAgentAddress parameter, should conform to one of the following forms.

Name/Address | Form (example)
IP Address | 157.57.8.160
IP Hostname | merlin.microsoft.com
Ethernet Address | 00aa00bbccdd
IPX Address | 00006112.00aa00bbccdd

Remarks

Names can be provided for agents only if TCP/IP is loaded and the names are TCP/IP host names. NetBIOS names cannot be supplied for IPX hosts.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrClose, SnmpMgrRequest


SnmpMgrRequest

The SnmpMgrRequest function requests the specified operation be performed with the specified agent. This function is an element of the SNMP Management API.

SNMPAPI SnmpMgrRequest(
  LPSNMP_MGR_SESSION session,         // SNMP session pointer
  BYTE requestType,                   // Get, GetNext, or Set
  SnmpVarBindList *variableBindings,  // variable bindings
  AsnInteger *errorStatus,            // SNMPv1 error status
  AsnInteger *errorIndex              // error index
);

Parameters

session
[in] Pointer to an internal structure that specifies the session that will perform the request.
requestType
[in] Specifies the SNMP request type. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_PDU_GET | Retrieve the value or values of the specified variables.
SNMP_PDU_GETNEXT | Retrieve the value or values of the lexicographic successor of the specified variable.
SNMP_PDU_SET | Write a value within a specific variable.

Note that PDU request types have been renamed. For additional information, see Modified SNMP PDU Request Types.

variableBindings
[in/out] Pointer to the variable bindings list.
errorStatus
[out] Pointer to a variable in which the error status result will be returned. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_ERRORSTATUS_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERRORSTATUS_TOOBIG | The agent could not place the results of the requested operation into a single SNMP message.
SNMP_ERRORSTATUS_NOSUCHNAME | The requested operation identified an unknown variable.
SNMP_ERRORSTATUS_BADVALUE | The requested operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERRORSTATUS_READONLY | The requested operation tried to change a variable that was not allowed to change according to the community profile of the variable.
SNMP_ERRORSTATUS_GENERR | An error other than one of those listed here occurred during the requested operation.

errorIndex
[out] Pointer to a variable in which the error index result will be returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError. GetLastError may return one of the following error codes.

Error Code | Meaning
SNMP_MGMTAPI_TIMEOUT | The request timed-out.
SNMP_MGMTAPI_SELECT_FDERRORS | Unexpected error file descriptors indicated by the Windows Sockets select function.

Remarks

Retries and time-outs are supplied to the SnmpMgrOpen function. Each variable in the variable bindings list must be initialized to type ASN_NULL for Get and Get Next requests.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOpen, SnmpMgrClose


SnmpMgrStrToOid

The SnmpMgrStrToOid function converts the string format of an object identifier to its internal object identifier structure. This function is an element of the SNMP Management API.

BOOL SnmpMgrStrToOid(
  LPSTR string,             // string to convert
  AsnObjectIdentifier *oid  // object identifier representation
);

Parameters

string
[in] Pointer to a null-terminated string to convert.
oid
[out] Pointer to an object identifier variable to receive the converted value.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function does not return Windows Sockets error codes.

Remarks

If an application passes a valid object identifier to SnmpMgrStrToOid, yet is unable to obtain the requested variable, then the syntax of the system group and object identifier is incorrect. This occurs because SnmpMgrStrToOid assumes that the object identifier is under the Internet MIB of the management subtree.

You must always precede the object identifier with a period (.) to obtain the correct system group (for example, ".1.3.6.1.2.1.1"). If an application passes the variable "1.3.6.1.2.1.1", SnmpMgrStrToOid cannot interpret the object identifier correctly.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOidToStr


SnmpMgrTrapListen

The SnmpMgrTrapListen function registers the ability of an SNMP manager application to receive SNMP traps from the SNMP Trap Service. This function is an element of the SNMP Management API.

BOOL SnmpMgrTrapListen(
  HANDLE *phTrapAvailable  // event handle indicating a trap
                           // is available
);

Parameters

phTrapAvailable
[out] Pointer to an event handle to receive an indication that there are traps available, and that the application should call the SnmpMgrGetTrap function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return any of the following error codes.

Error Code | Description
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error.
SNMP_MGMTAPI_TRAP_DUPINIT | Indicates that this function has already been called.
SNMP_MGMTAPI_AGAIN | Indicates an error occurred; the application can attempt to call the function again.

This function may return other system errors as well.

Remarks

It is important to note that the SnmpMgrTrapListen function succeeds on Windows NT® versions 4.0 and later only if the SNMP trap service has been started.

The application must always call the SnmpMgrTrapListen function before calling the SnmpMgrGetTrap function. This is because the event handle pointed to by the phTrapAvailable parameter enables the event-driven acquisition of SNMP traps. The SNMP Management API signals an application's event when the SNMP Trap Service delivers a trap.

The application can also poll the SnmpMgrGetTrap function for traps at regular intervals. In this case, the application should repeatedly call SnmpMgrGetTrap until the function returns zero.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mgmtapi.h.
Import Library: Use mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrGetTrap


SnmpSvcGetUptime

[This is preliminary documentation and subject to change.]

The SnmpSvcGetUptime function retrieves the number of centiseconds that the SNMP service has been running. This function is an element of the SNMP Utility API.

DWORD SnmpSvcGetUptime(
);

Parameters

This function has no parameters.

Return Values

The function returns a DWORD value that is the number of centiseconds the SNMP service has been running.

Remarks

An extension agent should call the SnmpSvcGetUptime function only if the extension agent DLL is loaded within the address space of the SNMP service.

The SNMP extension agent DLL is encouraged to use the SnmpSvcGetUptime function to retrieve the number of centiseconds that the SNMP service has been running. Extension agents should use SnmpSvcGetUptime rather than calculate the uptime using the dwUptimeReference parameter. The service passes this parameter to the extension agent as the result of a call to the SnmpExtensionInit function. Because the dwUptimeReference parameter stores the elapsed time as a DWORD value in milliseconds, the time can wrap to zero and reflect an inaccurate time interval.

An extension agent that sends traps must initialize the timeStamp parameter to the SnmpExtensionTrap function with the value returned by a call to the SnmpSvcGetUptime function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionTrap


SnmpSvcSetLogLevel

[This is preliminary documentation and subject to change.]

The SnmpSvcSetLogLevel function adjusts the level of detail of the debug output from the SNMP service and from SNMP extension agents using the SnmpUtilDbgPrint function. This function is an element of the SNMP Utility API.

VOID SnmpSvcSetLogLevel(
  INT nLogLevel  // level of severity of the event
);

Parameters

nLogLevel
Specifies a signed integer variable that indicates the level of detail of the debug output from the SnmpUtilDbgPrint function. This parameter can be one of the following values.
Value | Meaning
SNMP_LOG_SILENT | Disable all debugging output.
SNMP_LOG_FATAL | Display fatal errors only.
SNMP_LOG_ERROR | Display recoverable errors.
SNMP_LOG_WARNING | Display warnings and recoverable errors.
SNMP_LOG_TRACE | Display trace information.
SNMP_LOG_VERBOSE | Display verbose trace information.

Return Values

None.

Remarks

Extension agents are encouraged to use the SnmpSvcSetLogType and SnmpSvcSetLogLevel functions during development to adjust the output of debugging information. Extension agents can integrate the information with the debug output from the SNMP service.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilDbgPrint, SnmpSvcSetLogType


SnmpSvcSetLogType

[This is preliminary documentation and subject to change.]

The SnmpSvcSetLogType function adjusts the destination for the debug output from the SNMP service and from SNMP extension agents using the SnmpUtilDbgPrint function. This function is an element of the SNMP Utility API.

VOID SnmpSvcSetLogType(
  INT nLogType  // destination for debug output
);

Parameters

nLogType
Specifies a signed integer variable that represents the destination for the debug output from the SnmpUtilDbgPrint function. This parameter can be one of the following values.
Value | Meaning
SNMP_OUTPUT_TO_CONSOLE | The destination for the debug output is a console window.
SNMP_OUTPUT_TO_LOGFILE | The destination for the debug output is the SNMPDBG.LOG file in the SYSTEM32 directory.
SNMP_OUTPUT_TO_DEBUGGER | The destination for the debug output is a debugger utility.

Return Values

None.

Remarks

Extension agents are encouraged to use the SnmpSvcSetLogType and SnmpSvcSetLogLevel functions during development to adjust the output of debugging information. Extension agents can integrate the information with the debug output from the SNMP service.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilDbgPrint, SnmpSvcSetLogLevel


SnmpUtilAsnAnyCpy

[This is preliminary documentation and subject to change.]

The SnmpUtilAsnAnyCpy function copies the variable pointed to by the pAnySrc parameter to the pAnyDst parameter. The function allocates any necessary memory for the destination's copy. The SnmpUtilAsnAnyCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilAsnAnyCpy(
  AsnAny *pAnyDst,  // destination structure
  AsnAny *pAnySrc   // source structure
);

Parameters

pAnyDst
Pointer to an AsnAny structure to receive the copy.
pAnySrc
Pointer to an AsnAny structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilAsnAnyFree function to free the memory that the SnmpUtilAsnAnyCpy function allocates for the destination structure.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny, SnmpUtilAsnAnyFree


SnmpUtilAsnAnyFree

[This is preliminary documentation and subject to change.]

The SnmpUtilAsnAnyFree function frees the memory allocated for the specified AsnAny structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilAsnAnyFree(
  AsnAny *pAny  // pointer to structure to free
);

Parameters

pAny
Pointer to an AsnAny structure whose memory should be freed.

Return Values

None.

Remarks

Call the SnmpUtilAsnAnyFree function to free the memory that the SnmpUtilAsnAnyCpy function allocates.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny, SnmpUtilAsnAnyCpy


SnmpUtilDbgPrint

[This is preliminary documentation and subject to change.]

The SnmpUtilDbgPrint function enables debugging output from the SNMP service. This function is an element of the SNMP Utility API.

VOID SnmpUtilDbgPrint(
  INT nLogLevel,  // level of severity of event
  LPSTR szFormat  // pointer to a format string
);

Parameters

nLogLevel
Specifies a signed integer variable that indicates the level of detail of the log event. This parameter can be one of the following values.
Value | Meaning
SNMP_LOG_SILENT | Disable all debugging output.
SNMP_LOG_FATAL | Display fatal errors only.
SNMP_LOG_ERROR | Display recoverable errors.
SNMP_LOG_WARNING | Display warnings and recoverable errors.
SNMP_LOG_TRACE | Display trace information.
SNMP_LOG_VERBOSE | Display verbose trace information.

szFormat
Pointer to a null-terminated format string that is similar to the standard C library function printf style.

Return Values

None.

Remarks

Extension agents are encouraged to use this function during development to enable debug output from the SNMP service.

Use the SnmpSvcSetLogLevel function to set the level of detail of the debug output from the SNMP service or from an extension agent's call to the SnmpUtilDbgPrint function. Call the SnmpSvcSetLogType function to specify the destination for the debug output.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpSvcSetLogType, SnmpSvcSetLogLevel


SnmpUtilMemAlloc

The SnmpUtilMemAlloc function allocates dynamic memory from the process heap. This function is an element of the SNMP Utility API.

LPVOID SnmpUtilMemAlloc(
  UINT nBytes  // bytes to allocate for object
);

Parameters

nBytes
[in] Specifies the number of bytes to allocate for the memory object.

Return Values

If the function succeeds, the return value is a pointer to the newly allocated memory object.

If the function fails, the return value is NULL.

Remarks

Use the SnmpUtilMemFree function to release memory that the SnmpUtilMemAlloc function allocates.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemFree, SnmpUtilMemReAlloc


SnmpUtilMemFree

The SnmpUtilMemFree function frees the specified memory object. This function is an element of the SNMP Utility API.

VOID SnmpUtilMemFree(
  LPVOID pMem  // pointer to memory object to release
);

Parameters

pMem
[in/out] Pointer to the memory object to release.

Return Values

None.

Remarks

Call the SnmpUtilMemAlloc function to allocate the memory for the object.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemAlloc, SnmpUtilMemReAlloc


SnmpUtilMemReAlloc

The SnmpUtilMemReAlloc function changes the size of the specified memory object. This function is an element of the SNMP Utility API.

LPVOID SnmpUtilMemReAlloc(
  LPVOID pMem,  // pointer to memory object
  UINT nBytes   // bytes to allocate
);

Parameters

pMem
[in] Pointer to the memory object to resize.
nBytes
[in] Specifies the number of bytes to allocate for the new memory object.

Return Values

If the function succeeds, the return value is a pointer to the newly allocated memory object.

If the function fails, the return value is NULL.

Remarks

Call the SnmpUtilMemFree function to release memory that the SnmpUtilMemReAlloc function allocates.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpUtilOctetsCmp

[This is preliminary documentation and subject to change.]

The SnmpUtilOctetsCmp function compares two octet strings. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsCmp(
  AsnOctetString *pOctets1,  // first octet string
  AsnOctetString *pOctets2   // second octet string
);

Parameters

pOctets1
Pointer to an AsnOctetString structure to compare.
pOctets2
Pointer to a second AsnOctetString structure to compare.

Return Values

The function returns a value greater than zero if pOctets1 is greater than pOctets2, zero if pOctets1 equals pOctets2, and less than zero if pOctets1 is less than pOctets2.

Remarks

The SnmpUtilOctetsCmp function calls the SnmpUtilOctetsNCmp function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsNCmp


SnmpUtilOctetsCpy

[This is preliminary documentation and subject to change.]

The SnmpUtilOctetsCpy function copies the variable pointed to by the pOctetsSrc parameter to the variable pointed to by the pOctetsDst parameter. The function allocates any necessary memory for the destination's copy. The SnmpUtilOctetsCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsCpy(
  AsnOctetString *pOctetsDst,  // destination octet string
  AsnOctetString *pOctetsSrc   // source octet string
);

Parameters

pOctetsDst
Pointer to an AsnOctetString structure to receive the copy.
pOctetsSrc
Pointer to an AsnOctetString structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilOctetsFree function to free the memory that the SnmpUtilOctetsCpy function allocates for the destination structure.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsFree


SnmpUtilOctetsFree

[This is preliminary documentation and subject to change.]

The SnmpUtilOctetsFree function frees the memory allocated for the specified octet string. This function is an element of the SNMP Utility API.

VOID SnmpUtilOctetsFree(
  AsnOctetString *pOctets  // octet string to free
);

Parameters

pOctets
Pointer to an AsnOctetString structure whose memory should be freed.

Return Values

None.

Remarks

Call the SnmpUtilOctetsFree function to free the memory that the SnmpUtilOctetsCpy function allocates.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsCpy


SnmpUtilOctetsNCmp

[This is preliminary documentation and subject to change.]

The SnmpUtilOctetsNCmp function compares two octet strings. The function compares the subidentifiers in the strings until it reaches the number of subidentifiers specified by the nChars parameter. SnmpUtilOctetsNCmp is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsNCmp(
  AsnOctetString *pOctets1,  // first octet string
  AsnOctetString *pOctets2,  // second octet string
  UINT nChars                // maximum length to compare
);

Parameters

pOctets1
Pointer to an AsnOctetString structure to compare.
pOctets2
Pointer to a second AsnOctetString structure to compare.
nChars
Specifies the number of subidentifiers to compare.

Return Values

The function returns a value greater than zero if pOctets1 is greater than pOctets2, zero if pOctets1 equals pOctets2, and less than zero if pOctets1 is less than pOctets2.

Remarks

The SnmpUtilOctetsCmp function calls the SnmpUtilOctetsNCmp function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsCmp


SnmpUtilOidAppend

The SnmpUtilOidAppend function appends the source object identifier to the destination object identifier. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidAppend(
  AsnObjectIdentifier *pOidDst,  // destination object identifier
  AsnObjectIdentifier *pOidSrc   // source object identifier
);

Parameters

pOidDst
[in/out] Pointer to an AsnObjectIdentifier structure to receive the source structure.
pOidSrc
[in] Pointer to an AsnObjectIdentifier structure to append.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function does not generate Windows Sockets errors. The application should call the GetLastError function. GetLastError may return the following error codes.

Error Code | Description
SNMP_BERAPI_OVERFLOW | Indicates an overflow condition
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error

Remarks

The SnmpUtilOidAppend function calls the SnmpUtilMemReAlloc function. The SnmpUtilMemReAlloc function expands the buffer for the destination object identifier.

Call the SnmpUtilOidFree function to free memory that the SnmpUtilOidAppend function allocates for the destination.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemReAlloc, SnmpUtilOidFree


SnmpUtilOidCmp

The SnmpUtilOidCmp function compares two object identifiers. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidCmp(
  AsnObjectIdentifier *pOid1,  // first object identifier
  AsnObjectIdentifier *pOid2   // second object identifier
);

Parameters

pOid1
[in] Pointer to an AsnObjectIdentifier structure to compare.
pOid2
[in] Pointer to a second AsnObjectIdentifier structure to compare.

Return Values

The function returns a value greater than zero if pOid1 is greater than pOid2, zero if pOid1 equals pOid2, and less than zero if pOid1 is less than pOid2.

Remarks

The SnmpUtilOidCmp function calls the SnmpUtilOidNCmp function.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidNCmp


SnmpUtilOidCpy

The SnmpUtilOidCpy function copies the variable pointed to by the pOidSrc parameter to the pOidDst parameter, allocating any necessary memory for the destination's copy. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidCpy(
  AsnObjectIdentifier *pOidDst,  // destination object identifier
  AsnObjectIdentifier *pOidSrc   // source object identifier
);

Parameters

pOidDst
[out] Pointer to an AsnObjectIdentifier structure to receive the copy.
pOidSrc
[in] Pointer to an AsnObjectIdentifier structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilOidFree function to free memory that the SnmpUtilOidCpy function allocates for the destination structure.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidFree


SnmpUtilOidFree

The SnmpUtilOidFree function frees the memory allocated for the specified object identifier. This function is an element of the SNMP Utility API.

VOID SnmpUtilOidFree(
  AsnObjectIdentifier *pOid  // object identifier to free
);

Parameters

pOid
[in/out] Pointer to an AsnObjectIdentifier structure whose memory should be freed.

Return Values

None.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidAppend


SnmpUtilOidNCmp

The SnmpUtilOidNCmp function compares two object identifiers. The function compares the subidentifiers in the variables until it reaches the number of subidentifiers specified by the nSubIds parameter. SnmpUtilOidNCmp is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidNCmp(
  AsnObjectIdentifier *pOid1,  // first object identifier
  AsnObjectIdentifier *pOid2,  // second object identifier
  UINT nSubIds                 // maximum length to compare
);

Parameters

pOid1
[in] Pointer to an AsnObjectIdentifier structure to compare.
pOid2
[in] Pointer to a second AsnObjectIdentifier structure to compare.
nSubIds
[in] Specifies the number of subidentifiers to compare.

Return Values

The function returns a value greater than zero if pOid1 is greater than pOid2, zero if pOid1 equals pOid2, and less than zero if pOid1 is less than pOid2.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidCmp


SnmpUtilPrintAsnAny

The SnmpUtilPrintAsnAny function prints the value of the Any parameter to the standard output. This function is an element of the SNMP Utility API.

VOID SnmpUtilPrintAsnAny(
  AsnAny *pAny  // pointer to value to print
);

Parameters

pAny
[in] Pointer to an AsnAny structure for a value to print.

Return Values

None.

Remarks

Use the SnmpUtilPrintAsnAny function for debugging and development purposes. This function does not generally print the data in a form that a manager application would typically need.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny


SnmpUtilVarBindCpy

The SnmpUtilVarBindCpy function copies the specified SnmpVarBind structure, and allocates any memory necessary for the destination structure. The SnmpUtilVarBindCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilVarBindCpy(
  SnmpVarBind *pVbDst,  // destination variable bindings
  SnmpVarBind *pVbSrc   // source variable bindings
);

Parameters

pVbDst
[out] Pointer to an SnmpVarBind structure to receive the copy.
pVbSrc
[in] Pointer to an SnmpVarBind structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilVarBindFree function to free memory that the SnmpUtilVarBindCpy function allocates for the destination structure.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpUtilVarBindFree


SnmpUtilVarBindListCpy

The SnmpUtilVarBindListCpy function copies the specified SnmpVarBindList structure, and allocates any necessary memory for the destination's copy. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilVarBindListCpy(
  SnmpVarBindList *pVblDst,  // destination variable bindings list
  SnmpVarBindList *pVblSrc   // source variable bindings list
);

Parameters

pVblDst
[out] Pointer to an SnmpVarBindList structure to receive the copy.
pVblSrc
[in] Pointer to an SnmpVarBindList structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilVarBindListFree function to free memory that the SnmpUtilVarBindListCpy function allocates for the destination structure.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBindList, SnmpUtilVarBindListFree, SnmpUtilOidCpy


SnmpUtilVarBindFree

The SnmpUtilVarBindFree function frees the memory allocated for an SnmpVarBind structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilVarBindFree(
  SnmpVarBind *pVb  // variable binding to free
);

Parameters

pVb
[in/out] Pointer to an SnmpVarBind structure whose memory should be freed.

Return Values

None.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpUtilVarBindListFree


SnmpUtilVarBindListFree

The SnmpUtilVarBindListFree function frees the memory allocated for an SnmpVarBindList structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilVarBindListFree(
  SnmpVarBindList *pVbl  // variable bindings list to free
);

Parameters

pVbl
[in/out] Pointer to an SnmpVarBindList structure whose allocated memory should be freed.

Return Values

No return value.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: Use snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBindList, SnmpUtilVarBindFree


SNMP Structures

The following structures are used with SNMP.

AsnAny
AsnCounter64
AsnObjectIdentifier
AsnOctetString
SnmpVarBind
SnmpVarBindList


AsnAny

The AsnAny structure contains an SNMP variable type and value. This structure is a member of the SnmpVarBind structure that is used as a parameter in many of the SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    BYTE asnType;
     union {
       AsnInteger32         number;      // ASN_INTEGER
                                         // ASN_INTEGER32
       AsnUnsigned32        unsigned32;  // ASN_UNSIGNED32
       AsnCounter64         counter64;   // ASN_COUNTER64
       AsnOctetString       string;      // ASN_OCTETSTRING
       AsnBits              bits;        // ASN_BITS
       AsnObjectIdentifier  object;      // ASN_OBJECTIDENTIFIER
       AsnSequence          sequence;    // ASN_SEQUENCE
       AsnIPAddress         address;     // ASN_IPADDRESS
       AsnCounter32         counter;     // ASN_COUNTER32
       AsnGauge32           gauge;       // ASN_GAUGE32
       AsnTimeticks         ticks;       // ASN_TIMETICKS
       AsnOpaque            arbitrary;   // ASN_OPAQUE
} asnValue;
} AsnAny;

Members

asnType
Indicates the variable's type. This member must be only one of the following values.
Value | Meaning
ASN_INTEGER | Indicates a 32-bit signed integer variable.
ASN_INTEGER32 | Indicates a 32-bit signed integer variable.
ASN_UNSIGNED32 | Indicates a 32-bit unsigned integer variable.
ASN_COUNTER64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
ASN_OCTETSTRING | Indicates an octet string variable.
ASN_BITS | Indicates a variable that is an enumeration of named bits.
ASN_OBJECTIDENTIFIER | Indicates an object identifier variable.
ASN_SEQUENCE | Indicates an ASN sequence variable.
ASN_IPADDRESS | Indicates an IP address variable.
ASN_COUNTER32 | Indicates a counter variable.
ASN_GAUGE32 | Indicates a gauge variable.
ASN_TIMETICKS | Indicates a timeticks variable.
ASN_OPAQUE | Indicates an opaque variable.

asnValue
Contains the variable's value. This member can be only one of the following values.
Value | Meaning
number | Accesses a 32-bit signed integer variable.
unsigned32 | Accesses a 32-bit unsigned integer variable.
counter64 | Accesses a counter variable that increases until it reaches a maximum value of (2^64) – 1.
string | Accesses an octet string variable.
bits | Accesses a variable that is an enumeration of named bits with non-negative, contiguous values, starting at zero.
object | Accesses an object identifier variable.
sequence | Accesses an ASN sequence variable.
address | Accesses an IP address variable.
counter | Accesses a counter variable that increases until it reaches a maximum value of (2^32) – 1.
gauge | Accesses a gauge variable.
ticks | Accesses a timeticks counter variable that is relative to a specific timer event.
arbitrary | Accesses an opaque variable.

QuickInfo

Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpVarBind


AsnCounter64

[This is preliminary documentation and subject to change.]

The AsnCounter64 structure contains a 64-bit unsigned integer value and represents a 64-bit counter. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    ULONG   LowPart;    // low-order 32 bits
    ULONG   HighPart;   // high-order 32 bits
} AsnCounter64;

Members

LowPart
Specifies the low-order 32 bits of the counter.
HighPart
Specifies the high-order 32 bits of the counter.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, AsnAny


AsnObjectIdentifier

The AsnObjectIdentifier structure represents object identifiers. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    UINT idLength;  // length of oid
    UINT * ids ;    // pointer to oid array
} AsnObjectIdentifier;

Members

idLength
Specifies the number of integers in the object identifier.
ids
Pointer to an array of integers that represents the object identifier.

Remarks

None.

QuickInfo

Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures


AsnOctetString

The AsnOctetString structure contains octet quantities, usually bytes. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    BYTE  * stream;  //pointer to octet stream
    UINT  length;    //number of octets in stream
    BOOL  dynamic;   //dynamic allocation flag
} AsnOctetString;

Members

stream
Pointer to the octet stream.
length
The number of octets in the data stream.
dynamic
Flag that specifies whether the data stream has been dynamically allocated with the SnmpUtilMemAlloc function.

Remarks

Use the AsnOctetString structure to transfer string values. For example, use it to transfer the string that represents a computer name as a MIB object value.

You must check the flag specified in the dynamic member before you release the data stream of an octet string. Call the SnmpUtilMemFree function only if the dynamic member is set to TRUE.

QuickInfo

Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpUtilMemFree, SnmpUtilMemAlloc


SnmpVarBind

The SnmpVarBind structure represents an SNMP variable binding. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    AsnObjectName   name;   // variable name
    AsnObjectSyntax value;  // variable value
} SnmpVarBind;

Members

name
Indicates the variable's name, as an object identifier.
value
Contains the variable's value.

QuickInfo

Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures


SnmpVarBindList

The SnmpVarBindList structure represents an SNMP variable bindings list. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP Manager API functions.

typedef struct {
    SnmpVarBind *list;   //pointer to variable bindings
    UINT           len;  //number of variable binding entries
} SnmpVarBindList;

Members

list
A pointer that references an array to access individual variable bindings.
len
Contains the number of variable bindings in the list.

QuickInfo

Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpVarBind


WinSNMP Manager API

[This is preliminary documentation and subject to change.]

The Windows® SNMP Manager Application Programming Interface (the WinSNMP Manager API), version 1.1a, allows you to develop SNMP-based network management applications that execute in the Windows NT® operating environment, version 4.0 and later. The Simple Network Management Protocol (SNMP) is a request-response protocol that transfers management information between protocol entities.

WinSNMP has been jointly developed with the cooperation, input, and support from several companies, associations and individuals.

The first part of this overview provides information about SNMP versions, and a list of the relevant Requests for Comments (RFCs). It also describes the WinSNMP model, and the components and features of the Microsoft WinSNMP implementation. It also provides information about data management and communications concepts you need to program in the WinSNMP environment.

The second section discusses the WinSNMP functions and the following related WinSNMP programming tasks:

  • Opening and closing a WinSNMP manager application
  • Opening and closing a WinSNMP session
  • Managing traps and notifications
  • Working with variable binding lists
  • Working with protocol data units
  • Sending SNMP messages
  • Receiving SNMP messages
  • Managing object identifiers
  • Freeing WinSNMP descriptors
  • Setting the entity and context translation mode
  • Managing the retransmission policy

You should be familiar with the basic concepts of SNMP and Windows programming before reading this overview. For additional information about SNMP, see Simple Network Management Protocol and the relevant Requests for Comments (RFCs) which are published by the Internet Engineering Task Force (IETF).


About the WinSNMP Manager API

[This is preliminary documentation and subject to change.]

The WinSNMP Manager API is an interface for the development of SNMP-enabled network management applications.

The WinSNMP Manager API provides the following features:

  • SNMP-enabling technology for network management applications
  • SNMP version 1 (SNMPv1) and SNMP version 2C (SNMPv2C) support

The WinSNMP Manager API supports 32-bit applications, and it executes in single- and multi-threaded environments. Support for the WinSNMP Manager API is available for applications that execute in the Windows NT® operating environment, version 4.0 and later.


About SNMP Versions

[This is preliminary documentation and subject to change.]

The original Internet standard Network Management Framework, described in RFCs 1155, 1157, and 1213, is called the SNMP version 1 (SNMPv1) framework. Relevant portions of the proposed framework for version 2C of the Simple Network Management Protocol (SNMPv2C) are described in RFCs 1901 through 1908.

The WinSNMP Manager API supports the SNMP protocol functionality described in the relevant Internet RFCs. WinSNMP places no constraints on the use of SNMPv1 or SNMPv2C by WinSNMP manager applications.

A management entity can support a different version of SNMP than the one the WinSNMP manager application supports. The Microsoft WinSNMP implementation performs the appropriate translations from SNMPv1 to SNMPv2C in accordance with the relevant RFC.


RFCs Relevant to WinSNMP

[This is preliminary documentation and subject to change.]

TCP/IP standards are defined in Requests for Comments (RFCs), which are published by the Internet Engineering Task Force (IETF). The RFCs that are relevant to WinSNMP features are listed in the following table.

RFC number | Title
1155 | "Structure and Identification of Management Information for TCP/IP-based Internets"
1157 | "A Simple Network Management Protocol (SNMP)"
1213 | "Management Information Base for Network Management of TCP/IP-based internets: MIB-II"
1901 | "Introduction to Community-based SNMPv2"
1902 | "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1903 | "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1904 | "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1905 | "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1906 | "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1907 | "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1908 | "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework"
2089 | "V2ToV1 Mapping SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent"


Software Requirements for the WinSNMP Manager API

[This is preliminary documentation and subject to change.]

A WinSNMP manager application must access the WinSNMP Manager API through the dynamic-link library WSNMP32.DLL.

The following files are required to support the functionality of the WinSNMP Manager API.

Filename | Description
WSNMP.LIB | WinSNMP Library
WSNMP32.DLL | Provides WinSNMP interface
WINSNMP.H | WinSNMP header file
SNMPTRAP.EXE | Receives SNMP traps and forwards them to MGMTAPI.DLL, the Microsoft SNMP Manager API library
SNMPAPI.DLL | Provides SNMP utilities


The WinSNMP Model

[This is preliminary documentation and subject to change.]

The WinSNMP-compliant model includes the following basic components:

  • A WinSNMP-enabled SNMP network management application, that is, a WinSNMP-compliant manager application
  • The WinSNMP function layer
  • A WinSNMP-enabled SNMP service provider, that is, a WinSNMP-compliant implementation

Network management applications that must convey SNMP messages operate efficiently in an event-driven environment. This is because SNMP is a datagram-based or connectionless protocol between remote entities that do not establish virtual circuits.

Since Microsoft Windows applications are also event-driven, WinSNMP uses a programming model in which the receipt and processing of asynchronous message-events drive management applications. An asynchronous message-event can be an SNMP operation request by a manager application, or the response to a request by an agent application.

SNMP sends requests and responses as SNMP messages. An SNMP message is an SNMP protocol data unit (PDU) plus additional message header elements defined by the relevant RFC. For additional information, see About SNMP Messages, Working with Variable Binding Lists and Working with Protocol Data Units.


About the Microsoft WinSNMP Implementation

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation provides the following services for WinSNMP manager applications.

  • Manages communications to and from management entities. The entity can reside on the local computer or be connected through a local or wide-area network, or the Internet. For additional information, see Levels of SNMP Support.
  • Hides the details of SNMP protocol, Abstract Syntax Notation One (ASN.1), and the Basic Encoding Rules (BER) for describing transfer syntax.
  • Verifies the correctness of PDUs and rejects invalid PDUs. For additional information, see Working with Protocol Data Units.
  • Transforms SNMPv2C PDU types when necessary in accordance with the relevant RFCs.
  • Converts SNMPv1 traps from an SNMPv1 agent to SNMPv2C traps in accordance with RFC 1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework." For additional information, see Translating Traps from SNMPv1 to SNMPv2C.
  • Supports the application's retransmission policy and provides retransmission execution support. For additional information, see The WinSNMP Database and About Retransmission.
  • Provides entity and context translation support for the application. For additional information, see The WinSNMP Database and Setting the Entity and Context Translation Mode.

For additional information about the relationship between a WinSNMP manager application and the implementation, see WinSNMP Data Management Concepts and WinSNMP Sessions.


The WinSNMP Database

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation maintains a store of administrative information in a database. The database includes the following information:

  • Network and version properties. The implementation uses these properties to determine which network transport protocol and SNMP version framework to use to complete transmission requests. For additional information, see About SNMP Versions.
  • Entity and context translation mode. The implementation uses this mode to interpret user-friendly names for SNMP entities and contexts. For additional information, see Setting the Entity and Context Translation Mode.
  • Retransmission policy setting. The implementation uses this setting to determine whether or not it should execute the application's retransmission policy. The implementation stores a time-out value and a retry count for each destination entity. For additional information, see About Retransmission and Managing the Retransmission Policy.


Levels of SNMP Support

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation provides multiple levels of SNMP communications support. The levels are listed in the following table.

Level | Meaning
Level 0 | Support for message encoding and decoding only. Level 0 support does not provide communication transport services. This level does not support the SnmpSendMsg, SnmpRecvMsg, and SnmpRegister functions, because these functions require communication with other SNMP entities.
Level 1 | Support for Level 0 communications, as well as interaction with SNMP agent entities operating under the SNMP version 1 framework (SNMPv1).
Level 2 | Support for Level 1 communications, as well as interaction with SNMP agent entities operating under the SNMP version 2C framework (SNMPv2C).

The implementation returns the maximum level of SNMP communications it supports in response to a call by the WinSNMP manager application to the SnmpStartup function.

If the WinSNMP manager application uses the implementation for SNMP message encoding and decoding only, the application must perform required transformations that the implementation would have performed. This includes translating SNMPv1 traps returned by a call to the SnmpRecvMsg function, to SNMPv2C traps. It also includes translating PDU types defined by SNMPv1 to the relevant PDU type defined by SNMPv2C, in accordance with RFC 1908.


WinSNMP Sessions

[This is preliminary documentation and subject to change.]

A session is the basic unit of resource and communications management between a calling WinSNMP manager application and the Microsoft WinSNMP implementation. It is recommended that a manager application use sessions to organize its operations and reduce the demand on the implementation's resources.

For additional information, see Opening and Closing a WinSNMP Session.


WinSNMP Data Management Concepts

[This is preliminary documentation and subject to change.]

The topics in this section cover the major concepts of data management that apply to programming with the WinSNMP Manager API.

  • Object identifiers
  • WinSNMP Descriptors
  • Resource handle objects
  • C-style strings
  • Allocating WinSNMP memory objects


Object Identifiers

[This is preliminary documentation and subject to change.]

An SNMP object identifier uniquely names an object and identifies its location within a Management Information Base (MIB) tree structure. Object identifiers are application-independent Abstract Syntax Notation One (ASN.1) data types that consist of a sequence of non-negative integers, or subidentifiers. Object identifiers must have a minimum of two subidentifiers and they must not exceed 128 subidentifiers.

The WinSNMP programming environment uses the smiOID structure to manage object identifiers. The format of the object identifier array in an smiOID structure is one subidentifier per array element.

The dotted numeric string representation of an object identifier separates its subidentifiers with periods; for example, "1.2.3.4.5.6".

For additional information, see The SNMP Management Information Base (MIB) and the relevant RFCs.


WinSNMP Descriptors

[This is preliminary documentation and subject to change.]

In the WinSNMP programming environment a descriptor is one of the following two structures:

  • An smiOCTETS structure which describes an octet string variable
  • An smiOID structure which describes an SNMP object identifier variable

A WinSNMP descriptor is a structure that has two members: a length member, len, and a pointer member, ptr. The ptr member points to the octet string or object identifier of interest. The ptr member can be either the smiLPBYTE or smiLPUINT32 data type.

An smiOCTETS descriptor or an smiOID descriptor can be the value member of an smiVALUE structure. The smiVALUE structure describes the value associated with a variable name in a variable binding entry.

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS and smiOID structures. Therefore, the application must call the SnmpFreeDescriptor function to free the memory for the ptr member of these structures.

String members in descriptors do not require a NULL terminating byte. For additional information about managing the memory allocated for descriptors, see Allocating WinSNMP Memory Objects.


Resource Handle Objects

[This is preliminary documentation and subject to change.]

The structure of a resource object is restricted to the Microsoft WinSNMP implementation. A WinSNMP manager application can access a resource object with a handle.

The implementation can allocate one of the following types of resource handles for a WinSNMP manager application.

Handle type | Description
HSNMP_SESSION | Handle to a WinSNMP session
HSNMP_ENTITY | Handle to an SNMP entity
HSNMP_CONTEXT | Handle to a WinSNMP context
HSNMP_PDU | Handle to a protocol data unit
HSNMP_VBL | Handle to a variable binding list

A WinSNMP manager application can request that the implementation create or delete resource handles, but the implementation performs the operation. For additional information about freeing individual resources, see the SnmpFreeDescriptor, SnmpFreeVbl, SnmpFreePdu, SnmpFreeEntity, and SnmpFreeContext functions.


C-Style Strings

[This is preliminary documentation and subject to change.]

A WinSNMP manager application can use NULL-terminated C-style strings to convert entity and object identifier (OID) objects to and from their string representations.

The WinSNMP functions that manipulate C-style strings include SnmpStrToEntity, SnmpEntityToStr, SnmpStrToOid, and SnmpOidToStr. Because SnmpEntityToStr and SnmpOidToStr return a pointer to a C-style string variable, the WinSNMP manager application must pass an appropriate value in the size parameter when it makes calls to these functions.

Note The context parameter of the SnmpStrToContext and SnmpContextToStr functions must be an octet string structure, that is, an smiOCTETS structure. The context parameter cannot be a C-style string. The string contained in an smiOCTETS structure does not require a NULL-terminating byte.


Allocating WinSNMP Memory Objects

[This is preliminary documentation and subject to change.]

Descriptors, resource handles and C-style strings are the three types of memory objects in the WinSNMP programming environment.

The type of object determines whether the Microsoft WinSNMP implementation or the WinSNMP manager application allocates and deallocates the memory for the object. This reduces unnecessary allocation of temporary buffer space and unnecessary copying of buffers.

The following table summarizes the allocation and deallocation of resources for WinSNMP memory objects.

Object type | Description
smiOID or smiOCTETS descriptor | If the WinSNMP manager application allocates the memory, it must deallocate the memory with a call to an appropriate function. If the implementation allocates the memory, the application must call the SnmpFreeDescriptor function to deallocate the memory.
smiVALUE structure | If the value member is an smiOID or an smiOCTETS descriptor, the application must proceed as indicated above for descriptors.
Resource handle | The implementation allocates, manages, and frees the memory.
C-style string | The WinSNMP manager application must manage and free the memory it allocates.

For additional information, see Freeing WinSNMP Descriptors.


WinSNMP Communications Management Concepts

[This is preliminary documentation and subject to change.]

The WinSNMP Manager API provides network transport independence for SNMP-based network management applications that execute in the Microsoft Windows NT® operating environment. The topics in this section cover concepts of communications management that apply to programming with WinSNMP.

  • About SNMP Messages
  • About Traps and Notifications
  • About Retransmission


About SNMP Messages

[This is preliminary documentation and subject to change.]

The Simple Network Management Protocol uses messages to communicate and exchange information between remote SNMP entities. SNMP messages contain protocol data units (PDUs) plus additional message header elements defined by the relevant RFC. A PDU is a data packet that contains SNMP data components (or fields).

The format of an SNMP message is the same for both SNMPv1 and SNMPv2C. However, SNMPv2C supports additional PDU types. For example, it supports the SNMP_PDU_GETBULK request type, which enables a manager application to efficiently retrieve large blocks of data from target entities.


Translating Message Requests

[This is preliminary documentation and subject to change.]

If a WinSNMP manager application requests functionality that is available under the SNMP version 2C framework (SNMPv2C), but the target entity supports only the SNMP version 1 framework (SNMPv1), the Microsoft WinSNMP implementation attempts to translate the request to the SNMPv1 format. To do this, the implementation uses the procedures defined in RFC 1908, "Coexistence Between Version 1 and Version 2 of the Internet-Standard Network Management Framework." If translation is not possible, the SnmpSendMsg function fails with the extended error code SNMPAPI_OPERATION_INVALID.


About Traps and Notifications

[This is preliminary documentation and subject to change.]

One type of message an SNMP agent application can send to a WinSNMP manager application is an asynchronous message that informs the application of a significant event. An example of a significant event is when a network link shuts down or when an authentication failure occurs.

These types of messages are called traps under SNMPv1 and notifications under SNMPv2C. The Microsoft WinSNMP implementation always translates SNMPv1 traps to the SNMPv2C format, as defined by RFC 1908.

For additional information, see the following topics:

  • Translating Traps from SNMPv1 to SNMPv2C
  • Trap Formats


Translating Traps from SNMPv1 to SNMPv2C

[This is preliminary documentation and subject to change.]

When the Microsoft WinSNMP implementation receives traps from an entity operating under the SNMPv1 framework, it translates the traps to the SNMPv2C format. Therefore, when SnmpRecvMsg delivers a trap it is always in the SNMPv2C format. RFC 1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework," specifies the rules for translating from the SNMPv1 to the SNMPv2C trap format.

A WinSNMP manager application can check the last variable binding entry in a variable binding list to determine if the entry is a trap translated from the SNMPv1 to the SNMPv2C format. If so, the last variable binding will always be equal to the value "snmpTrapEnterpriseOID.0".


Trap Formats

[This is preliminary documentation and subject to change.]

The format of Trap PDUs is different than that of other PDUs. The format of SNMPv1 traps and SNMPv2C traps is also different.

Under the SNMPv2C framework, the PDU trap format is a variable binding list of n variable binding entries organized in the following manner:

  • The first variable binding entry contains a time-stamp.
  • The second variable binding entry is an object identifier that identifies the trap.
  • The third through n variable binding entries, if present, contain additional information associated with the trap.

Under the SNMPv1 framework, the PDU trap format is as follows.

Field | Description
enterprise | Identifies the type of device that generated the trap
agent-addr | Identifies the IP address of the device that generated the trap
generic-trap/specific-trap | Identifies a predefined trap type
time-stamp | Identifies when the trap was generated
variable-bindings | Contains additional information associated with the trap

The SnmpRecvMsg function always returns a message in the SNMPv2C format. If the message contains the operation type SNMP_PDU_TRAP, the application can read the variable binding entries of the message and retrieve the information associated with the trap.


About Retransmission

[This is preliminary documentation and subject to change.]

A WinSNMP manager application can make SNMP operation requests in various ways. The application can issue several requests to an SNMP agent, without waiting for a response, or it can issue a single request and wait for the response. Since SNMP can be implemented on multiple transport protocols, delivery mechanisms and reliability characteristics can vary.

When you code the WinSNMP manager application you must determine the level of reliability you need for communications operations, based on the way the application issues operation requests. Then you must select a retransmission strategy and implement a retransmission policy.

A retransmission policy includes a time-out period and a retry count. A time-out period is the elapsed time, in hundredths of a second, between an application's issuance of an SnmpSendMsg request and its receipt of the corresponding message. The application receives the message as a result of a call to the SnmpRecvMsg function. The time-out value is the period of time the Microsoft WinSNMP implementation waits for an entity to respond to a communication request. If there is no response within the time-out period, the implementation either retransmits the request if the retry count value specifies retransmission attempts, or it fails the call to SnmpSendMsg. A retry count is the maximum number of retransmission attempts the implementation makes if an SNMP transmission request fails.

The implementation stores time-out values and retry counts in its database for the application. The implementation stores individual values for each destination entity.

Manager applications must establish their own polling frequencies and they must manage timer variables. For additional information, see Managing the Retransmission Policy.


WinSNMP Programming Tasks

[This is preliminary documentation and subject to change.]

The following table summarizes the basic programming procedures that you must perform to code a WinSNMP manager application, and the topics that provide information about these tasks.

Programming task | Task-related function and topics
Open the WinSNMP application. | Use SnmpStartup. See Opening and Closing a WinSNMP Manager Application.
Open one or more WinSNMP sessions. | Use SnmpOpen. See Opening and Closing a WinSNMP Session.
Register to receive traps or notifications. | Use SnmpRegister. See Managing Traps and Notifications.
Create one or more variable binding lists for incorporation in a PDU. | Use SnmpCreateVbl, SnmpDuplicateVbl, SnmpSetVb. See Working with Variable Binding Lists. Note: The application may need to call other variable binding functions to create the variable binding list.
Create one or more PDUs for transmission and processing. | Use SnmpCreatePDU, SnmpSetPduData, SnmpDuplicatePDU. See Working with Protocol Data Units. Note: The application may need to call other PDU functions and WinSNMP utility functions to create the PDU.
Submit one or more SNMP operation requests. | Use SnmpSendMsg. See Sending SNMP Messages.
Retrieve the response to the SNMP operation request. | Use SnmpRecvMsg. See Receiving SNMP Messages.
Process the request response. | Use application-specific logic.
Close each WinSNMP session. | Use SnmpClose. See Opening and Closing a WinSNMP Session.
Close the WinSNMP application. | Use SnmpCleanup. See Opening and Closing a WinSNMP Manager Application.

The following topics contain additional information about other general programming concepts specific to the WinSNMP environment.

General programming tasks Managing Object Identifiers

Freeing WinSNMP Descriptors

Setting the Entity and Context Translation Mode

Managing the Retransmission Policy

In addition, the WinSNMP manager application may need to incorporate calls to the following WinSNMP functions: SnmpFreeVbl, SnmpFreeEntity, SnmpFreeDescriptor, SnmpFreeContext, and SnmpFreePdu. This enables the Microsoft WinSNMP implementation to free WinSNMP memory objects. As a general rule, the WinSNMP manager application should free all resources allocated as the result of a call to a WinSNMP function. For additional information about deallocating resources, see Allocating WinSNMP Memory Objects.


Opening and Closing a WinSNMP Manager Application

[This is preliminary documentation and subject to change.]

The WinSNMP manager application must call the SnmpStartup function successfully before it calls any other WinSNMP function. The SnmpStartup function enables the Microsoft WinSNMP implementation to perform initialization procedures. The function also returns to the application the version of the WinSNMP Manager API that the implementation supports, the level of SNMP communications it supports, and the implementation's default translation and retransmission modes.

The WinSNMP manager application must call the SnmpCleanup function when the application no longer requires the implementation's services. Even though SnmpCleanup enables the implementation to deallocate all resources allocated to the application, it is recommended that the application first call the SnmpClose function once for each open WinSNMP session, to maximize the implementation's performance. The WinSNMP manager application must call SnmpCleanup as the last WinSNMP function before it terminates.


Opening and Closing a WinSNMP Session

[This is preliminary documentation and subject to change.]

To open a session, a manager application calls the SnmpOpen function. If the function completes successfully, the Microsoft WinSNMP implementation opens a session, and the function returns a session identifier in the form of an HSNMP_SESSION handle. All WinSNMP functions that return handle variables include the session identifier as an input parameter. This enables the implementation to use the handle to efficiently manage resources at the session level.

An application can have multiple sessions open at one time. Multiple sessions within an application can share handle variables.

If the implementation cannot open a session because of resource limitations, it returns SNMPAPI_FAILURE when the application calls SnmpOpen. If the application then calls the SnmpGetLastError function, it returns SNMPAPI_ALLOC_ERROR.

A call to the SnmpClose function enables the implementation to free any remaining resources and to close the session.

For additional information, see Resource Handle Objects and WinSNMP Sessions.


Managing Traps and Notifications

[This is preliminary documentation and subject to change.]

The WinSNMP manager application must register to receive traps and notifications by calling the SnmpRegister function with SNMPAPI_ON. The application can unregister and disable traps and notifications by calling the function with SNMPAPI_OFF.

Several options are available when the application calls SnmpRegister. The application can register or unregister for the following traps and notifications:

  • One type of trap or notification
  • All traps and notifications
  • All sources of trap and notification requests
  • Traps and notifications from all management entities
  • Traps and notifications for every context

To register and receive a predefined trap or notification type, the application must define an object identifier (an smiOID structure) for each predefined type. The structure must contain a pattern-matching sequence for the type of trap or notification. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," defines trap and notification object identifiers.

To retrieve outstanding trap data and notifications for a WinSNMP session, a WinSNMP manager application must call the SnmpRecvMsg function with the session handle returned by the SnmpOpen function.

For additional information, see Sending SNMP Messages and Receiving SNMP Messages. For additional information about allocation and deallocation of resources for traps and notifications, see Allocating WinSNMP Memory Objects.


Working with Variable Binding Lists

[This is preliminary documentation and subject to change.]

A variable binding is the pairing of an SNMP object instance name with an associated value. A variable binding list is a series of variable binding entries. In the WinSNMP programming environment, a protocol data unit (PDU) includes a variable binding list.

The details of the variable binding list structure are restricted to the Microsoft WinSNMP implementation. A WinSNMP manager application can access a variable binding list with a handle of the type HSNMP_VBL. For additional information, see Resource Handle Objects.

The WinSNMP manager application can construct and manipulate variable binding lists, and include them in PDUs. To perform these operations, the manager application uses the WinSNMP variable binding functions. For additional information about working with WinSNMP and variable binding lists, see the following topics:

  • Creating a Variable Binding List
  • Managing a Variable Binding List

For additional information about variable bindings and variable binding lists, see RFC1905, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)," and the WinSNMP Variable Binding Functions.


Creating a Variable Binding List

[This is preliminary documentation and subject to change.]

The SnmpCreateVbl function creates a new variable binding list. If the WinSNMP manager application specifies a variable name and a value, the function creates the list and adds the name and value as the first entry in the list. If the application specifies NULL for the variable name, the function creates an empty list.

To copy a variable binding list, call the SnmpDuplicateVbl function. The function creates a new variable binding list and initializes the new list with a copy of the data in the source variable binding list.

The SnmpCreateVbl function and the SnmpDuplicateVbl function allocate any necessary memory for the new variable binding list. The WinSNMP manager application must release the resources associated with these lists. It is recommended that the application do this by matching each call to SnmpCreateVbl and SnmpDuplicateVbl with a corresponding call to the SnmpFreeVbl function when it is appropriate to free the allocated memory.


Managing a Variable Binding List

[This is preliminary documentation and subject to change.]

The SnmpGetVb function retrieves variable binding information from a variable binding list. The function retrieves the variable name and the variable's associated value from the variable binding entry specified by the WinSNMP manager application.

To update variable binding entries in a variable binding list, call the SnmpSetVb function. The SnmpSetVb function also appends new variable binding entries to an existing variable binding list.

The WinSNMP manager application must call the SnmpDeleteVb function to remove entries from a variable binding list.

To retrieve, modify or delete a variable binding entry, the WinSNMP manager application must specify the position of the entry in the variable binding list.

A call to the SnmpSetPduData function associates a variable binding list with a PDU. A call to the SnmpGetPduData function retrieves a variable binding list from a PDU. An individual variable binding is not directly associated with a PDU, but it is indirectly associated through its inclusion in a variable binding list.


Working with Protocol Data Units

[This is preliminary documentation and subject to change.]

The Simple Network Management Protocol sends operation requests and responses as SNMP messages. An SNMP message is an SNMP protocol data unit (PDU) plus additional message header elements defined by the relevant RFC. A PDU includes a variable binding list.

The structure of a PDU is restricted to the Microsoft WinSNMP implementation. A WinSNMP manager application can access a PDU with a handle of the type HSNMP_PDU. The WinSNMP manager application must create a PDU before it calls the SnmpSendMsg function or the SnmpEncodeMsg function.

The application can extract and update the data elements of a PDU, and release resources allocated for PDUs. To perform these operations, the manager application uses the WinSNMP PDU functions. For additional information about working with PDUs in the WinSNMP programming environment, see the following topics:

  • Creating a PDU
  • Updating a PDU
  • Duplicating a PDU
  • Validating a PDU
  • Matching Response and Request PDUs

For additional information, see Working with Variable Binding Lists and Resource Handle Objects.


Creating a PDU

[This is preliminary documentation and subject to change.]

To create and initialize a PDU a WinSNMP manager application calls the SnmpCreatePdu function. The application must call SnmpCreatePdu before it calls the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit a PDU. The application must also call SnmpCreatePdu before it calls the SnmpEncodeMsg function to request encoding of an SNMP message.

The application must call the SnmpFreePdu function to release the resources that the SnmpCreatePdu function allocates for new PDUs.


Updating a PDU

[This is preliminary documentation and subject to change.]

A WinSNMP manager application can retrieve and update selected PDU fields by using the SnmpGetPduData and the SnmpSetPduData functions.

The application can retrieve the PDU type, request identifier, error status, and error index fields from a specific PDU. It can also retrieve the handle to the variable binding list. The application can update the PDU_type and request_id fields.

If the PDU type is equal to SNMP_PDU_GETBULK, the application can also update the non_repeaters and the max_repetitions fields of the PDU.


Duplicating a PDU

[This is preliminary documentation and subject to change.]

The SnmpDuplicatePdu function duplicates a PDU, allocating any necessary memory. To release resources allocated by SnmpDuplicatePdu for a new PDU, a WinSNMP manager application must call the SnmpFreePdu function.


Validating a PDU

[This is preliminary documentation and subject to change.]

When the WinSNMP manager application calls the SnmpSendMsg function or the SnmpEncodeMsg function, the Microsoft WinSNMP implementation verifies the validity of the PDU and the other function parameters.

The value of one PDU data component (or field) can be valid individually, but it may be invalid in combination with values for other fields. For example, unless the PDU_type field of the PDU is SNMP_PDU_GETBULK or SNMP_PDU_RESPONSE, both the error_status and error_index fields must be equal to zero. Any other value combination constitutes an invalid PDU.

The implementation rejects invalid PDUs and returns the error status SNMPAPI_FAILURE. It sets an extended error code equal to SNMPAPI_PDU_INVALID.


Matching Response and Request PDUs

[This is preliminary documentation and subject to change.]

The order in which the WinSNMP manager application receives SNMP responses may not match the order in which the application submits SNMP operation requests. To match the response with the request, the application must use the request identifier field (the request_id) of the response.

The request_id field is a unique numeric value that identifies the PDU. Manager applications can assign request identifiers by calling the SnmpCreatePdu function or the SnmpSetPduData function. Call the SnmpGetPduData function to retrieve a PDU's request_id.


Assigning Request Identifiers

[This is preliminary documentation and subject to change.]

A WinSNMP manager application can call the SnmpCreatePdu function or the SnmpSetPduData function to assign an application-generated request identifier to a PDU. The application must pass the value in the request_id parameter.

An application can request that the Microsoft WinSNMP implementation generate and assign a request identifier to a PDU by passing zero in the request_id parameter of the SnmpCreatePdu function. The application can retrieve the assigned request identifier with a call to the SnmpGetPduData function.

To assign a request identifier equal to a specific value, including zero, the application must pass that value in the request_id parameter of the SnmpSetPduData function.

When the implementation executes the application's retransmission policy, it includes the request_id field of the original PDU in each retransmitted SNMP message. For additional information, see About Retransmission and Managing the Retransmission Policy.

Note When the implementation receives traps from an SNMPv1 entity, it assigns a non-zero value to the request_id field of the PDU. This value may duplicate a request identifier used by the application in a request PDU. Applications must check for duplication.


Sending SNMP Messages

[This is preliminary documentation and subject to change.]

A WinSNMP manager application initiates a transmission request by sending an SNMP message. SNMP messages include an SNMP protocol data unit. For additional information, see Working with Protocol Data Units.

A WinSNMP manager application must call the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit the PDU, with the other required message elements defined by the relevant RFC. In addition to the destination entity, the application must specify the source entity and a context for the request. The SnmpSendMsg function executes asynchronously.

The WinSNMP manager application must call the SnmpRecvMsg function to retrieve the response to an SnmpSendMsg request.

The implementation verifies the validity of the PDU and the other message elements when an application calls SnmpSendMsg.


Receiving SNMP Messages

[This is preliminary documentation and subject to change.]

The WinSNMP manager application must call the SnmpRecvMsg function to retrieve the response to an SnmpSendMsg request.

The SnmpOpen function passes an application window handle and a notification message identifier to the Microsoft WinSNMP implementation. When the application window receives this message, it signals the application to call the SnmpRecvMsg function using the session handle returned by SnmpOpen.

The SnmpRecvMsg function returns two entity handles, a context handle, and the handle to a PDU. It is recommended that the WinSNMP manager application free these resources using the SnmpFreeEntity, SnmpFreeContext, and SnmpFreePdu functions.

For additional information about managing the time between a call to the SnmpSendMsg function and the receipt of the corresponding response, see About Retransmission. For additional information about using the request_id PDU field to match a response PDU with its request PDU, see Matching Response and Request PDUs.


General WinSNMP Programming Tasks

[This is preliminary documentation and subject to change.]

The following topics contain information about general programming concepts specific to the WinSNMP environment.

  • Managing Object Identifiers
  • Freeing WinSNMP Descriptors
  • Setting the Entity and Context Translation Mode
  • Managing the Retransmission Policy


Managing Object Identifiers

[This is preliminary documentation and subject to change.]

The WinSNMP Manager API provides several WinSNMP utility functions that simplify the manipulation of object identifiers for WinSNMP manager applications.

The SnmpOidToStr function converts the internal binary representation of an object identifier to its dotted numeric string format. When you call SnmpOidToStr, specify a string buffer of MAXOBJIDSTRSIZE length (1408 bytes) to ensure that the output buffer is large enough to hold the converted string. To convert an object identifier from the dotted numeric string format to its internal binary representation, call the SnmpStrToOid function.

To copy an SNMP object identifier call the SnmpOidCopy function. This function allocates any necessary memory for the new object identifier.

A WinSNMP manager application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure specified by both the SnmpStrToOid and the SnmpOidCopy functions.

The SnmpOidCompare function compares two SNMP object identifiers. The WinSNMP manager application can specify the number of subidentifiers to compare. Call SnmpOidCompare to determine whether two object identifiers have common prefixes.

For additional information about managing the memory allocated for object identifiers, see Allocating WinSNMP Memory Objects.


Freeing WinSNMP Descriptors

[This is preliminary documentation and subject to change.]

The WinSNMP programming environment assigns the deallocation of descriptor resources to the WinSNMP implementation or the WinSNMP manager application, depending on which component allocates the memory for the descriptor.

To free the resources for an smiOID or an smiOCTETS descriptor, the following rules apply:

  • For input parameters

    Because the WinSNMP manager application allocates the memory for input objects with variable lengths, the application must free that memory using an appropriate function. For example, if the application allocated the resources with a call to the GlobalAlloc function, it should use the GlobalFree function to deallocate the resources. If the application allocated the resources with a call to the HeapAlloc function, it should call the HeapFree function.

  • For output parameters

    A call to any of the following functions results in the implementation allocating memory for an smiOID or an smiOCTETS descriptor: SnmpGetVb, SnmpEncodeMsg, SnmpOidCopy, SnmpContextToStr, and SnmpStrToOid.

    Because the implementation allocates the memory for these output objects, the application must call the SnmpFreeDescriptor function to deallocate the resources. This function enables the implementation to free the memory allocated for the ptr member of these structures.

To free the resources for an smiVALUE structure, the following rules apply:

A WinSNMP manager application must check the syntax member of an smiVALUE structure to correctly evaluate the value member of the structure. If the syntax member indicates that the value member is an smiOCTETS or an smiOID descriptor, and the implementation allocated the resources for the descriptor, the application must call SnmpFreeDescriptor. This enables the implementation to free the memory. If the application allocated the resources, it must free the memory using an appropriate function, as indicated earlier.

For additional information, see Allocating WinSNMP Memory Objects.


Setting the Entity and Context Translation Mode

[This is preliminary documentation and subject to change.]

The WinSNMP manager application can specify the interpretation and translation of entity and context parameters by setting the entity and context translation mode. The Microsoft WinSNMP implementation stores the mode in a database.

The setting of the entity and context translation mode determines the manner in which the SnmpStrToEntity function and the SnmpStrToContext function interpret input strings. The setting also determines the type of output string that the SnmpEntityToStr and the SnmpContextToStr functions return.

The implementation returns the current default entity and context translation mode in the nTranslateMode parameter of the SnmpStartup function. To retrieve the current entity and context translation mode in effect for the implementation, an application can call the SnmpGetTranslateMode function at any time.

The valid entity and context translation modes follow.

Mode | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as literal SNMP transport addresses, and context parameters as literal SNMP community strings.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as literal SNMP community strings.

The implementation tries to associate resources in its database with the literal transport address of the management entity.

To change the entity and context translation mode setting a WinSNMP manager application must call the SnmpSetTranslateMode function. If the requested translation mode is invalid, the function fails, and SnmpGetLastError returns the error code SNMPAPI_MODE_INVALID.


Managing the Retransmission Policy

[This is preliminary documentation and subject to change.]

The WinSNMP manager application can request that the Microsoft WinSNMP implementation execute the application's retransmission policy. When the implementation manages retransmission, it uses the time-out period and the retry count values in its database.

The implementation identifies the default retransmission mode in a return value from the SnmpStartup function during initialization. The mode can be one of the following values:

Value | Meaning
SNMPAPI_ON | The implementation is executing the application's retransmission policy.
SNMPAPI_OFF | The implementation is not executing the application's retransmission policy.

A WinSNMP manager application can retrieve the current retransmission mode in effect for the implementation with a call to the SnmpGetRetransmitMode function at any time. The WinSNMP Manager API provides other database functions that simplify management of the retransmission policy.

At any time during program execution, the WinSNMP manager application can adjust execution of the policy by performing one of the following steps:

  • Request that the implementation start or stop executing the retransmission policy by calling the SnmpSetRetransmitMode function. For additional information, see Turning Retransmission On and Off.
  • Modify the time-out period and retry count values in the implementation's database. For additional information, see Changing the Retransmission Policy.

The manager application can execute its own retransmission policy. In this case, execution may or may not be based on the values in the database.


Turning Retransmission On and Off

[This is preliminary documentation and subject to change.]

An application can set the retransmission mode with a call to the SnmpSetRetransmitMode function. The new retransmission mode applies to subsequent calls to the SnmpSendMsg function.

When the application calls SnmpSetRetransmitMode with the retransmission mode value SNMPAPI_ON, the Microsoft WinSNMP implementation begins execution of the application's retransmission policy. The new retransmission mode does not affect outstanding SNMP messages. An outstanding message is one that has no response at the time the manager application changes the retransmission mode.

When the WinSNMP manager application calls the SnmpSetRetransmitMode function with the retransmission mode value SNMPAPI_OFF, the implementation stops executing the retransmission policy. The implementation cancels retransmission attempts for outstanding SNMP messages. This is because it may not be possible for the implementation to handle all outstanding SNMP requests and operations plus new requests, before an application time-out or retry counter signals an event.


Changing the Retransmission Policy

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation provides retransmission policy support by storing a time-out value and a retry count for the WinSNMP manager application in a database. The implementation stores values for individual destination entities. The implementation initially supplies default values for these elements, but an application can add or modify values for individual entities.

A call to the SnmpGetTimeout and SnmpGetRetry functions returns the time-out and retry count values for a specific destination entity. To change the time-out value, a WinSNMP manager application must call the SnmpSetTimeout function. To change the retry count value the application must call the SnmpSetRetry function. The updated settings affect new SNMP message requests to the destination entity.


WinSNMP Manager API Reference

[This is preliminary documentation and subject to change.]

The following sections describe in detail the functions, structures, data types, function return values, and common error codes of the WinSNMP Manager API.

  • WinSNMP Data Types
  • WinSNMP Common Error Codes
  • WinSNMP Function Return Values
  • WinSNMP Functions
  • WinSNMP Structures


WinSNMP Data Types

[This is preliminary documentation and subject to change.]

The standard WinSNMP data types are defined in the WINSNMP.H file.

Note that WinSNMP specifies some parameters with the signed long integer type, smiINT. This enables WinSNMP to comply with the data elements, especially the PDU components, defined in the relevant RFCs.


WinSNMP Error Codes

[This is preliminary documentation and subject to change.]

Note The errors described in this topic are distinct from the SNMP error codes defined by the relevant RFCs.

All WinSNMP functions return the value SNMPAPI_FAILURE if the function fails. The WinSNMP manager application must immediately call the SnmpGetLastError function to retrieve extended error information when a WinSNMP function fails. For additional information about the extended error codes WinSNMP functions return, see the following topics:

  • WinSNMP Common Error Codes
  • Network Transport Errors

The WinSNMP errors that convey context-specific information are noted in each function's reference page.


WinSNMP Common Error Codes

[This is preliminary documentation and subject to change.]

The SnmpGetLastError function can return a general error code after a WinSNMP function fails. The following table lists the WinSNMP common error codes.

Error code | Meaning | Recommended action
SNMPAPI_ NOT_INITIALIZED | The SnmpStartup function did not complete successfully either since program execution began, or since a call to the SnmpCleanup function completed successfully. | The application should call SnmpGetLastError before it calls any other WinSNMP Manager API function when SnmpStartup fails. The SnmpGetLastError function returns extended error information about the failure of SnmpStartup.
SNMPAPI_ ALLOC_ERROR | An error occurred during memory allocation. The Microsoft WinSNMP implementation could not obtain sufficient resources to execute the request. | The application should free resources, reduce resource requirements, or facilitate a graceful shutdown. A graceful shutdown includes multiple calls to the SnmpClose function, one for each open WinSNMP session. It also includes a call to the SnmpCleanup function.
SNMPAPI_ OTHER_ERROR | An unknown or undefined error occurred. | The application should usually respond with a graceful shutdown. A graceful shutdown includes multiple calls to the SnmpClose function, one for each open WinSNMP session. It also includes a call to the SnmpCleanup function.

The WinSNMP errors that convey context-specific information are noted in each function's reference page.


Network Transport Errors

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation can detect a network transport error after it transmits an SNMP message. When this occurs, the implementation sends a data receipt notification to the WinSNMP session that initiated the communication request. The implementation also returns SNMPAPI_FAILURE on the next call to the SnmpRecvMsg function for the session. The SnmpRecvMsg function fails with an extended error code that indicates a network transport layer error.

For a list of specific transport layer errors, see the reference pages for the SnmpRegister, SnmpSendMsg, and SnmpRecvMsg functions.


WinSNMP Function Return Values

[This is preliminary documentation and subject to change.]

The return value from a WinSNMP function call can be a handle to a resource that the Microsoft WinSNMP implementation allocates for the WinSNMP manager application.

The following table lists the five types of resource handles that the implementation allocates.

Handle type | Description
HSNMP_SESSION | Handle to a WinSNMP session
HSNMP_ENTITY | Handle to an SNMP entity
HSNMP_CONTEXT | Handle to an SNMP context
HSNMP_PDU | Handle to a protocol data unit
HSNMP_VBL | Handle to a variable binding list

For additional information, see Resource Handle Objects.

The return value can also be an unsigned long integer value of the smiUINT32 type that represents an SNMPAPI_STATUS value.

The following table lists the WinSNMP status values and their meaning.

Status | Description
SNMPAPI_FAILURE | Indicates an error. Equates to 0 or NULL.
SNMPAPI_SUCCESS | Indicates the function completed successfully. Equates to 1 or a positive count.


WinSNMP Functions

[This is preliminary documentation and subject to change.]

The functions used with WinSNMP fall into the following functional groupings:

  • Communications Functions
  • Entity and Context Functions
  • Database Functions
  • PDU Functions
  • Utility Functions
  • Variable Binding Functions

WinSNMP Communications Functions

The WinSNMP communications functions provide an interface between the calling WinSNMP manager application and the Microsoft WinSNMP implementation. The implementation handles communication between the application and other management entities.

Function | Description
SnmpCleanup | Informs the implementation that a manager application is disconnecting and no longer requires allocated resources. A manager application must call the SnmpCleanup function as the last WinSNMP function before it terminates.
SnmpClose | Enables the implementation to deallocate resources associated with a session, and to close communications mechanisms.
SnmpCreateSession | Requests the implementation to open a WinSNMP session and allocate resources and communications mechanisms. This function provides an alternative to the SnmpOpen function for manager applications that are not Windows-based.
SnmpOpen | Requests the implementation to open a WinSNMP session and allocate resources and communications mechanisms.
SnmpRecvMsg | Returns SNMP messages and outstanding trap data and notifications.
SnmpRegister | Informs the implementation that the manager application needs to register or unregister for traps and notifications.
SnmpSendMsg | Requests that the implementation transmit a protocol data unit.
SnmpStartup | Notifies the implementation to perform initialization procedures for the manager application. A manager application must call the SnmpStartup function successfully before it calls any other WinSNMP function.
SNMPAPI_CALLBACK | Notifies a WinSNMP session that an SNMP message or asynchronous event is available. Note: This callback function applies only to sessions opened as a result of a call to the SnmpCreateSession function.

WinSNMP Entity and Context Functions

The WinSNMP entity and context functions enable a WinSNMP manager application to specify user-friendly names for SNMP entities and contexts. The Microsoft WinSNMP implementation translates the name to its SNMPv1 or SNMPv2C components using the implementation's database.

Function | Description
SnmpContextToStr | Returns a string that identifies an SNMP context (a set of managed object resources).
SnmpEntityToStr | Returns a string that identifies an SNMP management entity.
SnmpFreeContext | Releases resources allocated by the SnmpStrToContext function for an SNMP context.
SnmpFreeEntity | Releases resources allocated by the SnmpStrToEntity function for an SNMP management entity.
SnmpStrToContext | Returns a handle to SNMP context information that is specific to the implementation.
SnmpStrToEntity | Returns a handle to SNMP management entity information that is specific to the implementation.

WinSNMP Database Functions

The WinSNMP database functions provide a WinSNMP manager application with access to the current settings in the Microsoft WinSNMP implementation's store of administrative information. These functions permit changing the retransmission mode and the entity and context translation mode. The database functions also provide the manager application with the ability to manipulate the time-out and retry count values.

Function | Description
SnmpGetRetransmitMode | Returns the current setting of the retransmission mode.
SnmpGetRetry | Returns the retry count value, in units, for the retransmission of SNMP message requests.
SnmpGetTimeout | Returns the time-out value, in hundredths of a second, for the transmission of SNMP message requests.
SnmpGetTranslateMode | Returns the current setting of the entity and context translation mode.
SnmpSetRetransmitMode | Changes the retransmission mode.
SnmpSetRetry | Changes the retry count value for the retransmission of SNMP message requests.
SnmpSetTimeout | Changes the time-out value for the transmission of SNMP message requests.
SnmpSetTranslateMode | Changes the entity and context translation mode.

WinSNMP PDU Functions

The WinSNMP PDU functions enable WinSNMP manager applications to extract and update the data elements (or fields) of a PDU. This includes PDUs returned by a call to the SnmpRecvMsg function or the SnmpDecodeMsg function. The PDU functions also construct PDUs for use in the SnmpSendMsg and SnmpEncodeMsg functions.

Function | Description
SnmpCreatePdu | Creates and initializes an SNMP protocol data unit.
SnmpDuplicatePdu | Duplicates an SNMP protocol data unit.
SnmpFreePdu | Releases resources associated with an SNMP protocol data unit created by the SnmpCreatePdu or the SnmpDuplicatePdu function.
SnmpGetPduData | Returns selected data elements from a specified SNMP protocol data unit.
SnmpSetPduData | Updates selected data elements in a specified SNMP protocol data unit.

WinSNMP Utility Functions

The WinSNMP utility functions enable a WinSNMP manager application to manage objects and SNMP messages across the WinSNMP interface.

Function | Description
SnmpDecodeMsg | Decodes an encoded or serialized SNMP message into its constituent components.
SnmpEncodeMsg | Creates an encoded SNMP message.
SnmpFreeDescriptor | Signals the Microsoft WinSNMP implementation that it should free the memory it allocated for a specific descriptor.
SnmpGetLastError | Returns the last-error code value for the last SNMP operation.
SnmpOidCompare | Compares two SNMP object identifiers.
SnmpOidCopy | Copies an SNMP object identifier.
SnmpOidToStr | Converts the internal binary representation of an SNMP object identifier to its dotted numeric string format.
SnmpStrToOid | Converts the dotted numeric string format of an SNMP object identifier to its internal binary representation.

WinSNMP Variable Binding Functions

The WinSNMP variable binding functions enable WinSNMP manager applications to construct and manipulate variable binding lists, and include them in PDUs.

Function | Description
SnmpCountVbl | Enumerates the variable binding entries in a specified variable binding list.
SnmpCreateVbl | Creates a new variable binding list.
SnmpDeleteVb | Removes a variable binding entry from a variable binding list.
SnmpDuplicateVbl | Copies a variable binding list.
SnmpFreeVbl | Releases resources for a variable binding list allocated previously by the SnmpCreateVbl or the SnmpDuplicateVbl function.
SnmpGetVb | Retrieves information from a specified variable binding entry.
SnmpSetVb | Changes variable binding entries in a variable binding list; appends new variable binding entries to an existing variable binding list.


SNMPAPI_CALLBACK

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation calls the SNMPAPI_CALLBACK function to notify a WinSNMP session that an SNMP message or asynchronous event is available.

SNMPAPI_CALLBACK is a placeholder for an application- or library-defined callback function name.

SNMPAPI_STATUS CALLBACK SNMPAPI_CALLBACK(
  HSNMP_SESSION hSession,  // handle to the WinSNMP session
  HWND hWnd,               // handle to the notification window
  UINT wMsg,               // window notification message number
  WPARAM wParam,           // type of notification
  LPARAM lParam,           // request identifier of PDU
  LPVOID lpClientData      // optional application-defined data
);

Parameters

hSession
Handle to the WinSNMP session.
hWnd
Handle to a window of the WinSNMP manager application to notify when an asynchronous request completes, or when trap notification occurs. This parameter does not have significance for the WinSNMP session, but the implementation always passes the value to the callback function.
wMsg
Specifies an unsigned integer that identifies the notification message to send to the WinSNMP manager application window. This parameter does not have significance for the WinSNMP session, but the implementation always passes the value to the callback function.
wParam
Specifies an application-defined 32-bit value that identifies the type of notification. If this parameter is equal to zero, an SNMP message is available for the session. The manager application should call the SnmpRecvMsg function to retrieve the message. If this parameter is not equal to zero, it indicates an asynchronous event notification for the session. For additional information, see the following Remarks section.
lParam
Specifies an application-defined 32-bit value that specifies the request identifier of the PDU being processed.
lpClientData
If the lpClientData parameter was not NULL on the call to the SnmpCreateSession function for this session, this parameter is a pointer to application-defined data.

Return Values

The function must return SNMPAPI_SUCCESS to continue execution of the manager application. If the function returns any other value, the implementation responds as if the manager application called the SnmpClose function for the indicated session.

Remarks

When the implementation is executing the retransmission policy for the WinSNMP manager application and a transmission time-out occurs, the implementation informs the session of the error. In this situation the value of the wParam parameter would be SNMPAPI_TL_TIMEOUT. For a list of other transport layer errors, see the reference pages for the SnmpRegister, SnmpSendMsg, and SnmpRecvMsg functions.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: User-defined.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpCreateSession, SnmpClose, SnmpOpen


SnmpCleanup

[This is preliminary documentation and subject to change.]

The SnmpCleanup function informs the Microsoft WinSNMP implementation that the calling WinSNMP manager application no longer requires the implementation's services.

Note A WinSNMP manager application must call the SnmpCleanup function as the last WinSNMP function before it terminates.

SNMPAPI_STATUS SnmpCleanup(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS. Until the WinSNMP manager application successfully recalls the SnmpStartup function, any other call to a WinSNMP function returns SNMPAPI_FAILURE, with an extended error code of SNMPAPI_NOT_INITIALIZED.

If the function fails, the return value is SNMPAPI_FAILURE, but the WinSNMP manager application does not need to retry the call to SnmpCleanup. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Before the WinSNMP manager application calls SnmpCleanup, it should call the SnmpClose function once for each session the implementation opens as a result of a call to the SnmpOpen function.

When a WinSNMP manager application calls the SnmpCleanup function, the implementation deallocates all resources allocated to the application. However, it is recommended that a WinSNMP manager application free the specific resources that the implementation allocates for it with the WinSNMP function that corresponds to the resource. For additional information about freeing individual resources, see SnmpFreeEntity, SnmpFreeVbl, SnmpFreeDescriptor, SnmpFreeContext, and SnmpFreePdu.

If a WinSNMP manager application must perform an emergency exit, and it calls SnmpCleanup without freeing individual resources and without calling SnmpClose for every open session, the implementation deallocates all resources allocated to the WinSNMP manager application. However, to enable this functionality in the implementation, the application must still call SnmpCleanup.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpOpen, SnmpStartup, SnmpClose, SnmpFreeEntity, SnmpFreeVbl, SnmpFreeDescriptor, SnmpFreeContext, SnmpFreePdu


SnmpClose

[This is preliminary documentation and subject to change.]

The SnmpClose function enables the Microsoft WinSNMP implementation to deallocate memory, resources, and data structures associated with a WinSNMP session. The WinSNMP SnmpClose function also closes communications mechanisms the implementation opened as a result of a call to the SnmpOpen function.

SNMPAPI_STATUS SnmpClose(
  HSNMP_SESSION session    // handle to the session to close
);

Parameters

session
Handle to the WinSNMP session to close.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

It is recommended that a WinSNMP manager application call the SnmpClose function once for each session that the application opened using the SnmpOpen function. If a WinSNMP manager application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources. The implementation processes one SnmpCleanup call as if it were a series of SnmpClose calls, one call for each session opened as a result of a call to SnmpOpen.

When the implementation closes a session it discards all outstanding incoming and outgoing asynchronous requests and replies for the session. For additional information, see WinSNMP Sessions.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpCleanup, SnmpOpen


SnmpContextToStr

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpContextToStr function returns a string that identifies an SNMP context, which is a set of managed object resources. The function returns the string in an smiOCTETS structure.

SNMPAPI_STATUS SnmpContextToStr(
  HSNMP_CONTEXT context,  // handle to the context
  smiLPOCTETS string      // pointer to a structure to receive the
                          // context string
);

Parameters

context
Handle to the SNMP context of interest.
string
Pointer to an smiOCTETS structure to receive the string that identifies the context of interest. The string can have a null-terminating byte.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpContextToStr returns. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP manager application must provide the address of a valid smiOCTETS structure for the string parameter. If the SnmpContextToStr function completes successfully, the Microsoft WinSNMP implementation initializes the len and ptr members of the structure. The WinSNMP manager application must call the SnmpFreeDescriptor function to enable the implementation to free the resources for these members.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and the entry exists in the implementation's database, the implementation returns the associated user-friendly name of the context. If an entry does not exist for the context name, SnmpContextToStr returns the SNMP community string.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the implementation also returns the SNMP community string.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOCTETS


SnmpCountVbl

[This is preliminary documentation and subject to change.]

A WinSNMP manager application calls the WinSNMP SnmpCountVbl function to enumerate the variable binding entries in the specified variable bindings list.

SNMPAPI_STATUS SnmpCountVbl(
  HSNMP_VBL vbl   // handle to the variable bindings list
);

Parameters

vbl
Handle to the variable bindings list to enumerate.

Return Values

If the function succeeds, the return value is the count of variable binding entries in the variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_NOOP | The variable bindings list does not contain any variable binding entries at this time.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpCountVbl function returns an unsigned integer value that is the maximum value the WinSNMP manager application can specify for the index parameter in the SnmpGetVb, SnmpSetVb, and SnmpDeleteVb functions.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpGetVb, SnmpSetVb, SnmpDeleteVb


SnmpCreatePdu

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpCreatePdu function creates and initializes an SNMP protocol data unit (PDU).

HSNMP_PDU SnmpCreatePdu(
  HSNMP_SESSION session, // handle to the WinSNMP session
  smiINT PDU_type,       // PDU type
  smiINT32 request_id,   // PDU request identifier
  smiINT error_status,   // valid only for SNMP_PDU_GETBULK requests
  smiINT error_index,    // valid only for SNMP_PDU_GETBULK requests
  HSNMP_VBL varbindlist  // handle to the variable bindings list
);

Parameters

session
Handle to the WinSNMP session.
PDU_type
Specifies a PDU type that identifies the SNMP operation. This parameter can be NULL, or it can be one of the following values. If this parameter is NULL, the Microsoft WinSNMP implementation supplies the default PDU type SNMP_PDU_GETNEXT.
Value | Meaning
SNMP_PDU_GET | Search and retrieve a value from a specified SNMP variable.
SNMP_PDU_GETNEXT | Search and retrieve the value of an SNMP variable without knowing the exact name of the variable.
SNMP_PDU_RESPONSE | Reply to an SNMP_PDU_GET or an SNMP_PDU_GETNEXT request.
SNMP_PDU_SET | Store a value in a specified SNMP variable.
SNMP_PDU_V1TRAP | Alerts the management system to an extraordinary event under the SNMP version 1 (SNMPv1) framework. This type is obsolete in SNMP version 2C (SNMPv2C).
SNMP_PDU_GETBULK | Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP | Alerts the management system to an event under SNMPv2C.

request_id
Specifies a unique numeric value that the WinSNMP manager application supplies to identify the PDU. If this parameter is NULL, the implementation assigns a value.
error_status
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the non_repeaters field of the PDU. This parameter is ignored for other PDU types, and the implementation sets the value of this parameter to SNMP_ERROR_NOERROR. This parameter can be NULL.
error_index
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the max_repetitions field of the PDU. This parameter is ignored for other PDU types, and the implementation sets the value of this parameter to zero. This parameter can be NULL.
varbindlist
Handle to a structure that represents an SNMP variable bindings list. This parameter can be NULL.

Return Values

If the function succeeds, the return value is the handle to a new SNMP PDU.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_VBL_INVALID | The variable bindings list is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP manager application must create a PDU before it calls the SnmpSendMsg or the SnmpEncodeMsg functions.

All of the parameters of the SnmpCreatePdu function are required. However, all parameters, except the session parameter, can be NULL. In this instance, the new PDU has the following default values.

Field | Contents
PDU_type | SNMP_PDU_GETNEXT
request_id | The implementation generates a numeric value.
error_status | SNMP_ERROR_NOERROR
error_index | 0
varbindlist | NULL

The application must call the SnmpFreePdu function to release the resources that the SnmpCreatePdu function allocates for the new PDU.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreePdu, SnmpSendMsg, SnmpEncodeMsg


SnmpCreateSession

[This is preliminary documentation and subject to change.]

The SnmpCreateSession function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP manager application. The application can specify how the implementation should inform the WinSNMP session of available SNMP messages and asynchronous events. The application can specify a Windows notification message or an SNMPAPI_CALLBACK function to notify the session.

Note The SnmpCreateSession function is an element of the WinSNMP Manager API, version 2.0, which has not been finalized. The Microsoft WinSNMP implementation supports this function because it provides an alternative to the SnmpOpen function for manager applications that are not Windows-based.

HSNMP_SESSION SnmpCreateSession(
  HWND hWnd,                    // handle to the notification window
  UINT wMsg,                    // window notification message number
  SNMPAPI_CALLBACK pfnCallBack, // notification callback function
  LPVOID lpClientData           // pointer to callback function data
);

Parameters

hWnd
Handle to a window of the WinSNMP manager application to notify when an asynchronous request completes, or when trap notification occurs. This parameter is required for Windows notification messages for the session.
wMsg
Specifies an unsigned integer that identifies the notification message to send to the WinSNMP manager application window. This parameter is required for Windows notification messages for the session.
pfnCallBack
Specifies the address of an application-defined, session-specific SNMPAPI_CALLBACK function. The implementation will call this function to inform the WinSNMP session when notifications are available.

This parameter is required to specify callback notifications for the session. This parameter must be NULL to specify Windows notification messages for the session. For additional information, see the following Remarks section.

lpClientData
Pointer to application-defined data to pass to the callback function specified by the pfnCallBack parameter. This parameter is optional and can be NULL. If the pfnCallBack parameter is NULL, the implementation ignores this parameter.

Return Values

If the function succeeds, the return value is a handle that identifies the WinSNMP session that the implementation opens for the calling manager application.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_HWND_INVALID | The pfnCallBack parameter is NULL, but the hWnd parameter is not a valid window handle.
SNMPAPI_MSG_INVALID | The pfnCallBack parameter is NULL, but the wMsg parameter is not a valid message value.
SNMPAPI_MODE_INVALID | The pfnCallBack parameter is NULL and the hWnd and wMsg parameters are valid individually. However, the values are mutually incompatible on the Windows platform.
SNMPAPI_OPERATION_INVALID | The combination of parameter values does not specify callback notifications or Windows notification messages.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

If the WinSNMP manager application calls the SnmpCreateSession function with a NULL pfnCallBack parameter, SnmpCreateSession provides the same functionality as the SnmpOpen function.

The SnmpCreateSession function returns a unique handle to each open WinSNMP session within the calling WinSNMP manager application. The application must use the session handle that SnmpCreateSession returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation.

It is recommended that a WinSNMP manager application call the SnmpClose function once for each session that the implementation opens as a result of a call to the SnmpCreateSession function. If a WinSNMP manager application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources.

Callback Notifications

If the pfnCallBack parameter is not NULL on a successful call to the SnmpCreateSession function, the implementation alerts the session to notifications using the callback function specified by the pfnCallBack parameter.

Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using callback notifications.

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Windows Notification Messages

The SnmpCreateSession function passes to the implementation the handle to an application window and a notification message identifier. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP manager application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpCreateSession.

One WinSNMP manager application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP manager application specify a unique wMsg parameter for each session.

Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using Windows notification messages.

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SNMPAPI_CALLBACK, SnmpOpen, SnmpClose, SnmpCleanup, SnmpRecvMsg


SnmpCreateVbl

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpCreateVbl function creates a new variable bindings list for the calling WinSNMP manager application. If the name and value parameters are not NULL, SnmpCreateVbl uses their values to create the first variable binding entry for the new variable bindings list. The SnmpCreateVbl function returns a handle to the new variable bindings list and allocates any necessary memory for it.

HSNMP_VBL SnmpCreateVbl(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  smiLPCOID name,         // pointer to the variable name
  smiLPCVALUE value       // pointer to the value to associate
                          // with the variable
);

Parameters

session
Handle to the WinSNMP session.
name
Pointer to an smiOID structure that contains the variable name for the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.
value
Pointer to an smiVALUE structure that contains a value to associate with the variable in the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is a handle to a new variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_OID_INVALID | The name parameter references an invalid smiOID structure.
SNMPAPI_SYNTAX_INVALID | The syntax member of the structure pointed to by the value parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpCreateVbl function uses the values of the name and value parameters to create and initialize the first variable binding entry of a new variable bindings list. If the name parameter is NULL, the Microsoft WinSNMP implementation ignores the value parameter and creates an empty variable bindings list.

If the name parameter is not NULL, but the value parameter is NULL, the implementation creates and initializes the first variable binding entry in the variable bindings list. It initializes the syntax member of the structure pointed to by the value parameter with the value SNMP_SYNTAX_NULL.

The WinSNMP manager application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP manager application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpFreeVbl, smiOID, smiVALUE


SnmpDecodeMsg

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpDecodeMsg function decodes an encoded SNMP message into its components. This function performs the opposite action of the WinSNMP SnmpEncodeMsg function.

SNMPAPI_STATUS SnmpDecodeMsg(
  HSNMP_SESSION session,     // handle to the WinSNMP session
  LPHSNMP_ENTITY srcEntity,  // handle to the source entity
  LPHSNMP_ENTITY dstEntity,  // handle to the target entity
  LPHSNMP_CONTEXT context,   // handle to the context
  LPHSNMP_PDU pdu,           // handle to the PDU
  smiLPCOCTETS msgBufDesc    // pointer to the message buffer
);

Parameters

session
Handle to the WinSNMP session. This parameter is required. For additional information, see the following Remarks section.
srcEntity
Pointer to a variable that receives a handle to the management entity.
dstEntity
Pointer to a variable that receives a handle to the target management entity.
context
Pointer to a variable that receives a handle to the context (a set of managed object resources) that the target management entity controls.
pdu
Pointer to a variable that receives a handle to the SNMP protocol data unit (PDU).
msgBufDesc
Pointer to an smiOCTETS structure that contains the SNMP message to decode into its components. The len member of the structure specifies the maximum number of bytes to process; the ptr member points to the encoded SNMP message.

Return Values

If the function succeeds, the return value is the number of decoded bytes. This value can be equal to, or less than, the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The pdu parameter is invalid.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient. No output parameters were created.
SNMPAPI_MESSAGE_INVALID | The SNMP message format in the buffer indicated by the msgBufDesc parameter is invalid. No output parameters were created.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The Microsoft WinSNMP implementation allocates resources to the WinSNMP manager application as a result of a successful call to the SnmpDecodeMsg function. It is recommended that the WinSNMP manager application free individual resources with the WinSNMP function that corresponds to the resource. For additional information, see Freeing WinSNMP Descriptors and WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpEncodeMsg, SnmpFreeEntity, SnmpFreeContext, SnmpFreePdu, SnmpSendMsg, smiOCTETS


SnmpDeleteVb

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpDeleteVb function removes a variable binding entry from a variable bindings list.

SNMPAPI_STATUS SnmpDeleteVb(
  HSNMP_VBL vbl,   // handle to the variable bindings list
  smiUINT32 index  // position of the variable binding entry
                   // in the list
);

Parameters

vbl
Handle to the variable bindings list to update.
index
Specifies an unsigned long integer variable that identifies the variable binding entry to remove. This variable contains the position of the variable binding entry, within the variable bindings list.

Valid values for this parameter are in the range from 1 to n, where 1 indicates the first variable binding entry in the variable bindings list, and n is the total number of entries in the variable bindings list. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP manager application can use the SnmpDeleteVb function to delete invalid variable binding entries. When an SNMP_PDU_RESPONSE protocol data unit (PDU) includes an error that indicates an invalid variable binding entry, the application can call SnmpDeleteVb to delete the entry. Then the application can resubmit the request PDU with a call to the SnmpSendMsg function, without the invalid variable binding entry in the variable bindings list. Request PDUs include the SNMP_PDU_GET, SNMP_PDU_GETNEXT, and SNMP_PDU_GETBULK PDU data types.

After the SnmpDeleteVb function deletes a variable binding entry, the index value of all entries after the deleted entry will decrement by one. A call to the SnmpCountVbl function returns the new total number of entries in the variable bindings list. The new total is one less than the count returned by a call to SnmpCountVbl before the current call to SnmpDeleteVb.

If a WinSNMP manager application calls the SnmpDeleteVb function and deletes the last variable binding entry in a variable bindings list, the result is an empty variable bindings list. The variable bindings list still has a valid handle and the WinSNMP manager application must release the handle with a call to the SnmpFreeVbl function.

The following are valid values to use for the index parameter:

  • The return value from a call to the SnmpCountVbl function
  • The error index field of an SNMP_PDU_RESPONSE PDU returned by a call to the SnmpRecvMsg function

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpCountVbl, SnmpRecvMsg, SnmpFreeVbl


SnmpDuplicatePdu

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpDuplicatePdu function duplicates the SNMP protocol data unit (PDU) that the PDU parameter identifies, allocating any necessary memory for the duplicate PDU.

HSNMP_PDU SnmpDuplicatePdu(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  HSNMP_PDU PDU               // handle to the PDU to duplicate
);

Parameters

session
Handle to the WinSNMP session.
PDU
Handle to the PDU to duplicate. The SnmpDuplicatePdu function provides a unique handle to each PDU within the calling application.

Return Values

If the function succeeds, the return value is a handle that identifies the new duplicate PDU.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_PDU_INVALID | The PDU handle is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

To release resources allocated by the SnmpDuplicatePdu function for a new PDU, a WinSNMP manager application must call the SnmpFreePdu function.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreePdu, SnmpGetPduData


SnmpDuplicateVbl

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpDuplicateVbl function copies a variable bindings list for the specified WinSNMP session. This function returns a handle to the copied variable bindings list and allocates any necessary memory for it.

HSNMP_VBL SnmpDuplicateVbl(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  HSNMP_VBL vbl           // handle to the variable bindings
                          // list to duplicate
);

Parameters

session
Handle to the WinSNMP session.
vbl
Handle to the variable bindings list to copy. The source variable bindings list can be empty.

Return Values

If the function succeeds, the return value is a handle to a new variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpDuplicateVbl function creates a new variable bindings list for the specified WinSNMP session. This function initializes the new list with a copy of the data in the source variable bindings list.

The handle the SnmpDuplicateVbl function returns is unique among the variable bindings list handles that are active within the WinSNMP manager application.

The WinSNMP manager application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP manager application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeVbl, SnmpCreateVbl


SnmpEncodeMsg

[This is preliminary documentation and subject to change.]

The Microsoft WinSNMP implementation uses the parameters passed in the WinSNMP SnmpEncodeMsg function to encode an SNMP message. The implementation returns the encoded SNMP message to the WinSNMP manager application in the buffer specified by the msgBufDesc parameter.

SNMPAPI_STATUS SnmpEncodeMsg(
  HSNMP_SESSION session,     // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,    // handle to the source entity
  HSNMP_ENTITY dstEntity,    // handle to the target entity
  HSNMP_CONTEXT context,     // handle to the context
  HSNMP_PDU pdu,             // handle to the PDU
  smiLPOCTETS msgBufDesc     // pointer to the message buffer
);

Parameters

session
Handle to the WinSNMP session.
srcEntity
Handle to the management entity that initiates the request to encode the SNMP message.
dstEntity
Handle to the target management entity.
context
Handle to the context (a set of managed object resources) that the target management entity controls.
PDU
Handle to the PDU that contains the SNMP operation request.
msgBufDesc
Pointer to an smiOCTETS structure that receives the encoded SNMP message.

Return Values

If the function succeeds, the return value is the length, in bytes, of the encoded SNMP message. This number is also the value of the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.

If the function fails, the return value is SNMPAPI_FAILURE. For additional information, see the following Remarks section. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The PDU parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The first five parameters passed to the SnmpEncodeMsg function are the same parameters that are passed to the SnmpSendMsg function.

The WinSNMP manager application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOCTETS structure. This is the structure pointed to by the msgBufDesc parameter. For additional information, see WinSNMP Data Management Concepts.

On input, the SnmpEncodeMsg function ignores the members of the structure pointed to by the msgBufDesc parameter. The implementation overwrites the members of the structure if the function completes successfully.

The implementation verifies the format of the first five input parameters. If one of the parameters is invalid, SnmpEncodeMsg returns SNMPAPI_FAILURE, and SnmpGetLastError returns an extended error code.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeDescriptor, SnmpDecodeMsg, SnmpSendMsg, smiOCTETS


SnmpEntityToStr

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpEntityToStr function returns a string that identifies an SNMP management entity.

SNMPAPI_STATUS SnmpEntityToStr(
  HSNMP_ENTITY entity, // handle to the entity
  smiUINT32 size,      // buffer size, in bytes, for output string
  LPSTR string         // pointer to the buffer to receive the
                       // output string
);

Parameters

entity
Handle to the SNMP management entity of interest.
size
Specifies the size, in bytes, of the buffer pointed to by the string parameter. The WinSNMP manager application must allocate a buffer that is large enough to contain the output string.
string
Pointer to a buffer to receive the null-terminated string that identifies the SNMP management entity of interest.

Return Values

If the function succeeds, the return value is the number of bytes, including a terminating null byte, that SnmpEntityToStr returns in the string buffer. This value can be less than or equal to the value of the size parameter, but it cannot be greater.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The entity parameter is invalid.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpEntityToStr returns. For additional information, see Setting the Entity and Context Translation Mode.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and an entry exists in the implementation's database, the implementation returns the associated user-friendly name of the management entity. If an entry does not exist for the management entity, SnmpEntityToStr returns the literal SNMP transport address of the management entity.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the Microsoft WinSNMP implementation also returns the literal SNMP transport address of the management entity.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToEntity


SnmpFreeContext

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpFreeContext function releases resources associated with an SNMP context, which is a set of managed object resources.

SNMPAPI_STATUS SnmpFreeContext(
  HSNMP_CONTEXT context    // handle to the context to release
);

Parameters

context
Handle to the SNMP context that will have its resources released.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

When the WinSNMP manager application calls the SnmpClose function or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocated for the WinSNMP session. However, it is recommended that the WinSNMP manager application free individual resources with the WinSNMP function that corresponds to the resource. For example, manager applications should call the SnmpFreeContext function to release resources allocated by a call to the SnmpStrToContext function. This reduces the implementation's work load, and should enhance the service of the implementation to all applications.

For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpStrToContext


SnmpFreeDescriptor

[This is preliminary documentation and subject to change.]

The WinSNMP manager application uses the SnmpFreeDescriptor function to inform the Microsoft WinSNMP implementation that it no longer requires access to a descriptor object. This WinSNMP function signals the implementation to free the memory it allocated for the descriptor object.

SNMPAPI_STATUS SnmpFreeDescriptor(
  smiUINT32 syntax,       // data type of target descriptor object
  smiLPOPAQUE descriptor  // pointer to the target descriptor object
);

Parameters

syntax
Specifies the syntax data type of the target descriptor object.
descriptor
Pointer to an smiOPAQUE structure that contains the target descriptor object to release.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SYNTAX_INVALID | The syntax parameter is invalid.
SNMPAPI_OPERATION_INVALID | The descriptor parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The implementation allocates and deallocates memory for output descriptor objects with variable lengths. This memory allocation and deallocation are restricted to the implementation, except for the interface that the SnmpFreeDescriptor function provides. For additional information, see Freeing WinSNMP Descriptors.

The implementation returns the SNMPAPI_OPERATION_INVALID error code if the descriptor parameter specifies a memory allocation that the implementation released in a prior call to SnmpFreeDescriptor. The function returns the same error code if the descriptor parameter specifies a memory allocation that the implementation did not make for the calling WinSNMP manager application.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToOid, SnmpOidCopy, SnmpEncodeMsg


SnmpFreeEntity

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpFreeEntity function releases resources associated with an SNMP management entity.

SNMPAPI_STATUS SnmpFreeEntity(
  HSNMP_ENTITY entity   // handle to the entity to release
);

Parameters

entity
Handle to the SNMP management entity that will have its resources released.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The entity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

When the WinSNMP manager application calls the SnmpClose function or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocated for the WinSNMP session. However, it is recommended that the WinSNMP manager application free individual resources by using the WinSNMP function that corresponds to the resource. For example, manager applications should call the SnmpFreeEntity function to release resources allocated by a call to the SnmpStrToEntity function. This reduces the implementation's work load, and should enhance the implementation's service to all applications.

For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpStrToEntity


SnmpFreePdu

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpFreePdu function releases resources associated with an SNMP protocol data unit (PDU) created by the SnmpCreatePdu or the SnmpDuplicatePdu function.

SNMPAPI_STATUS SnmpFreePdu(
  HSNMP_PDU PDU     // handle to the PDU to free
);

Parameters

PDU
Handle to the SNMP PDU to free.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_PDU_INVALID | The PDU handle is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

If the manager application calls the SnmpClose or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocates for the WinSNMP session. However, it is recommended that the application free individual resources with the WinSNMP function that corresponds to the resource. This reduces the implementation's work load, and should enhance the implementation's service to all applications. The application should use the SnmpFreeVbl function to deallocate variable bindings list resources. For additional information, see WinSNMP Data Management Concepts.

Under WinSNMP, a variable binding entry exists only within a variable bindings list, even if the variable bindings list contains just one entry.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeVbl, SnmpClose, SnmpCleanup


SnmpFreeVbl

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpFreeVbl function releases resources associated with a variable bindings list. These are resources allocated previously by a call to the SnmpCreateVbl function or the SnmpDuplicateVbl function in a WinSNMP manager application.

SNMPAPI_STATUS SnmpFreeVbl(
  HSNMP_VBL vbl       // handle to the variable bindings list
);

Parameters

vbl
Handle to the variable bindings list to release.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The WinSNMP manager application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP manager application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl.

If the application calls the SnmpClose or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocates for the WinSNMP session. However, even if the application does not reuse a variable bindings list handle, it is recommended that the application free individual variable bindings resources with the SnmpFreeVbl function. This reduces the implementation's work load, and should enhance its service to all applications. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpCreateVbl, SnmpClose, SnmpCleanup


SnmpGetLastError

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetLastError function returns the calling application's last-error code value. The value indicates the reason why the last function call executed by the WinSNMP manager application failed.

SNMPAPI_STATUS SnmpGetLastError(
  HSNMP_SESSION session     // handle to the WinSNMP session
);

Parameters

session
Handle to the WinSNMP session.

A single thread manager application can pass a NULL session value to SnmpGetLastError to retrieve last-error information for the entire application. For additional information, see the following Return Values section.

Return Values

If the session parameter is a valid WinSNMP session handle, the SnmpGetLastError function returns the last WinSNMP error that occurred for the indicated session.

If the session parameter is NULL — for example, if the SnmpStartup function fails, SnmpGetLastError returns the last WinSNMP error that occurred for the entire manager application.

Remarks

A WinSNMP manager application must call SnmpGetLastError immediately after a function fails, to retrieve the last-error code. If another function fails, it overwrites the last-error code set by the most recently failed function.

Although the session parameter accommodates both multithread and single-thread Windows operating environments, the potential still exists for the last-error code from one thread to overwrite the last-error code from another thread.

Note that SnmpGetLastError must be able to return the last-error code to a WinSNMP manager application under the following conditions:

  • After the SnmpStartup function fails
  • Before the SnmpOpen function creates any WinSNMP sessions for the instance of the application
  • After the SnmpClose function closes all WinSNMP sessions for the instance of the application
  • After the SnmpCleanup function disconnects the WinSNMP manager application from the Microsoft WinSNMP implementation

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStartup, SnmpOpen, SnmpClose, SnmpCleanup


SnmpGetPduData

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetPduData function returns selected data fields from a specified SNMP protocol data unit (PDU).

SNMPAPI_STATUS SnmpGetPduData(
  HSNMP_PDU PDU,            // handle to the PDU
  smiLPINT PDU_type,        // PDU_type field of the PDU
  smiLPINT32 request_id,    // request_id field of the PDU
  smiLPINT error_status,    // error_status field of the PDU
  smiLPINT error_index,     // error_index field of the PDU
  LPHSNMP_VBL varbindlist   // handle to the variable bindings list
);

Parameters

PDU
Handle to the SNMP PDU.
PDU_type
Pointer to a variable that receives the PDU_type field of the specified PDU. This parameter can be NULL, or one of the following values.
Value | Meaning
SNMP_PDU_GET | Search and retrieve a value from a specified SNMP variable.
SNMP_PDU_GETNEXT | Search and retrieve the value of an SNMP variable without knowing the exact name of the variable.
SNMP_PDU_RESPONSE | Reply to an SNMP_PDU_GET or an SNMP_PDU_GETNEXT request.
SNMP_PDU_SET | Store a value in a specified SNMP variable.
SNMP_PDU_V1TRAP | Alerts the management system to an extraordinary event under the SNMP version 1 (SNMPv1) framework. This type is obsolete in SNMP version 2C (SNMPv2C).
SNMP_PDU_GETBULK | Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP | Alerts the management system to an extraordinary event under SNMPv2C.

request_id
Pointer to a variable that receives the request_id field of the specified PDU. This parameter can be NULL.
error_status
Pointer to a variable that receives the error_status field of the specified PDU. If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the non_repeaters field of the PDU.

This parameter can be NULL, or one of the following values. The first six errors are common to the SNMP version 1 (SNMPv1) and SNMP version 2C frameworks (SNMPv2C). The remaining errors are available under SNMPv2C only.

Error Code | Meaning
SNMP_ERROR_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERROR_TOOBIG | The agent could not place the results of the requested SNMP operation into a single SNMP message.
SNMP_ERROR_NOSUCHNAME | The requested SNMP operation identified an unknown variable.
SNMP_ERROR_BADVALUE | The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERROR_READONLY | The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
SNMP_ERROR_GENERR | An error other than one of those listed here occurred during the requested SNMP operation.
SNMP_ERROR_NOACCESS | The specified SNMP variable is not accessible.
SNMP_ERROR_WRONGTYPE | The value specifies a type that is inconsistent with the type required for the variable.
SNMP_ERROR_WRONGLENGTH | The value specifies a length that is inconsistent with the length required for the variable.
SNMP_ERROR_WRONGENCODING | The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
SNMP_ERROR_WRONGVALUE | The value cannot be assigned to the variable.
SNMP_ERROR_NOCREATION | The variable does not exist, and the agent cannot create it.
SNMP_ERROR_ INCONSISTENTVALUE | The value is inconsistent with values of other managed objects.
SNMP_ERROR_ RESOURCEUNAVAILABLE | Assigning the value to the variable requires allocation of resources that are currently unavailable.
SNMP_ERROR_COMMITFAILED | No validation errors occurred, but no variables were updated.
SNMP_ERROR_UNDOFAILED | No validation errors occurred. Some variables were updated because it was not possible to undo their assignment.
SNMP_ERROR_ AUTHORIZATIONERROR | An authorization error occurred.
SNMP_ERROR_NOTWRITABLE | The variable exists but the agent cannot modify it.
SNMP_ERROR_ INCONSISTENTNAME | The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

error_index
Pointer to a variable that receives the error_index field of the specified PDU.

If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the max_repetitions field of the specified PDU. This parameter can be NULL.

varbindlist
Pointer to a variable that receives a handle to the variable bindings list field of the specified PDU. This parameter can be NULL. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_NOOP | All output parameters are NULL. The SNMP operation was not performed.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

All parameters of the SnmpGetPduData function are required. However, all parameters, except the PDU parameter, can be NULL. In parameters the application passes as NULL, the SnmpGetPduData function does not return a value.

The SnmpGetPduData function always returns a handle to a new variable bindings list object if the varbindlist parameter is not NULL. Additionally, if the PDU parameter specifies a new PDU, the function also attaches a handle to the new PDU.

When a manager application calls SnmpGetPduData with a varbindlist parameter that is not NULL, but the PDU parameter specifies an existing PDU, the function returns a handle to a new duplicate variable bindings list. The function call does not disturb the handle attached to the existing PDU. An existing PDU is one that an application creates with a call to the SnmpCreatePdu function, or one that the application receives and then reads using a call to SnmpGetPduData.

When a manager application creates a PDU with SnmpCreatePdu, or after the application reads a PDU using SnmpGetPduData, the Microsoft WinSNMP implementation expects that the application "knows" the values of the PDU fields. If an application reads a PDU a second time with SnmpGetPduData, the call results in a copy of the variable bindings list of the specified PDU. This type of call to SnmpGetPduData also duplicates the handle to the PDU.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpCreatePdu


SnmpGetRetransmitMode

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetRetransmitMode function returns the current setting of the retransmission mode to a WinSNMP manager application. The Microsoft WinSNMP implementation uses the retransmission mode to govern transmission time-outs and retransmission attempts on calls to the SnmpSendMsg function.

SNMPAPI_STATUS SnmpGetRetransmitMode(
  smiLPUINT32 nRetransmitMode  // current retransmission mode
);

Parameters

nRetransmitMode
Pointer to an unsigned long integer variable to receive the current retransmission mode in effect for the implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_ON | The implementation is executing the WinSNMP manager application's retransmission policy.
SNMPAPI_OFF | The implementation is not executing the WinSNMP manager application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. If SnmpGetRetransmitMode fails, the value of the nRetransmitMode parameter has no meaning for the application. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStartup, SnmpSetRetransmitMode


SnmpGetRetry

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetRetry function returns the retry count value, in units, for the retransmission of SNMP message requests. The retry count applies to calls that a WinSNMP manager application makes to the SnmpSendMsg function for a specified management entity.

SNMPAPI_STATUS SnmpGetRetry(
  HSNMP_ENTITY hEntity,      // destination management entity
  smiLPUINT32 nPolicyRetry,  // retry count value from the database
  smiLPUINT32 nActualRetry   // last actual or estimated response
                             // retry count
);

Parameters

hEntity
Handle to the destination management entity of interest.
nPolicyRetry
Pointer to an unsigned long integer variable to receive the retry count value for the specified management entity. This is a value that the Microsoft WinSNMP implementation stores in a database.
nActualRetry
Pointer to an unsigned long integer variable to receive the last actual or estimated response retry count for the destination entity, as reported by the implementation. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP manager application can modify the retry count value with a call to the SnmpSetRetry function.

The WinSNMP manager application can monitor the value of the nActualRetry parameter and compare it to the value of the nPolicyRetry parameter to optimize transmission performance. For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSetRetry, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpGetTimeout

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetTimeout function returns the time-out value, in hundredths of a second, for the transmission of SNMP message requests. The time-out value applies to calls that a WinSNMP manager application makes to the SnmpSendMsg function for a specified management entity.

SNMPAPI_STATUS SnmpGetTimeout(
  HSNMP_ENTITY hEntity,          // destination management entity
  smiLPTIMETICKS nPolicyTimeout, // time-out value from the database
  smiLPTIMETICKS nActualTimeout  // last actual or estimated
                                 // response time
);

Parameters

hEntity
Handle to the destination management entity of interest.
nPolicyTimeout
Pointer to an integer variable to receive the time-out value, in hundredths of a second, for the specified management entity. This is a value that the Microsoft WinSNMP implementation stores in a database.
nActualTimeout
Pointer to an integer variable to receive the last actual or estimated response interval for the destination entity, as reported by the implementation. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The time-out period is the interval between the application's call to the SnmpSendMsg function and its call to the SnmpRecvMsg function.

A WinSNMP manager application can modify the time-out value with a call to the SnmpSetTimeout function.

The WinSNMP manager application can monitor the value of the nActualTimeout parameter and compare it to the value of the nPolicyTimeout parameter to optimize transmission performance. For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSetTimeout, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpGetTranslateMode

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpGetTranslateMode function returns the current setting of the entity and context translation mode to a WinSNMP manager application. The entity and context translation mode affects the interpretation and return of WinSNMP input and output string parameters.

SNMPAPI_STATUS SnmpGetTranslateMode(
  smiLPUINT32 nTranslateMode  // current entity/context translation
                              // mode
);

Parameters

nTranslateMode
Pointer to an unsigned long integer variable to receive the entity and context translation mode in effect for the Microsoft WinSNMP implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. If SnmpGetTranslateMode fails, the value of the nTranslateMode parameter has no meaning for the application. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The entity and context translation mode affects calls to the SnmpStrToEntity, SnmpStrToContext, SnmpContextToStr and SnmpEntityToStr functions. For additional information, see Setting the Entity and Context Translation Mode.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToContext, SnmpStrToEntity, SnmpContextToStr, SnmpEntityToStr, SnmpStartup, SnmpSetTranslateMode


SnmpGetVb

[This is preliminary documentation and subject to change.]

A WinSNMP manager application calls the SnmpGetVb function to retrieve information from a variable bindings list. This WinSNMP function retrieves a variable name and its associated value from the variable binding entry specified by the index parameter.

SNMPAPI_STATUS SnmpGetVb(
  HSNMP_VBL vbl,    // handle to the variable bindings list
  smiUINT32 index,  // position of the variable binding entry
                    // in the list
  smiLPOID name,    // pointer to the structure to receive the
                    // variable name
  smiLPVALUE value  // pointer to the structure to receive the
                    // associated value
);

Parameters

vbl
Handle to the variable bindings list to retrieve.
index
Specifies an unsigned long integer variable that identifies the variable binding entry to retrieve. This variable contains the position of the variable binding entry, within the variable bindings list.

Valid values for this parameter are in the range from 1 to n, where 1 indicates the first variable binding entry in the variable bindings list, and n is the total number of entries in the list. For additional information, see the following Remarks section.

name
Pointer to an smiOID structure to receive the variable name of the variable binding entry.
value
Pointer to an smiVALUE structure to receive the value associated with the variable identified by the name parameter.

If the function succeeds, the syntax member of the structure pointed to by the value parameter can be one of the following syntax data types. For additional information, see RFC 1902, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)."
Syntax data type | Meaning
SNMP_SYNTAX_INT | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_BITS | Indicates a variable that is an enumeration of named bits with non-negative, contiguous values, starting at zero.
SNMP_SYNTAX_OCTETS | Indicates an octet string variable that is binary or textual data.
SNMP_SYNTAX_NULL | Indicates a NULL value.
SNMP_SYNTAX_OID | Indicates an object identifier variable that is an assigned name with a maximum of 128 subidentifiers.
SNMP_SYNTAX_INT32 | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_IPADDR | Indicates a 32-bit Internet address variable.
SNMP_SYNTAX_CNTR32 | Indicates a counter variable that increases until it reaches a maximum value of (2^32) – 1.
SNMP_SYNTAX_GAUGE32 | Indicates a gauge variable that is a non-negative integer that can increase or decrease, but never exceed a maximum value.
SNMP_SYNTAX_TIMETICKS | Indicates a counter variable that measures the time in hundredths of a second, until it reaches a maximum value of (2^32) – 1. It is a non-negative integer that is relative to a specific timer event.
SNMP_SYNTAX_OPAQUE | This type provides backward compatibility, and should not be used for new object types. It supports the capability to pass arbitrary Abstract Syntax Notation One (ASN.1) syntax.
SNMP_SYNTAX_CNTR64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
SNMP_SYNTAX_UINT32 | Indicates a 32-bit unsigned integer variable.
SNMP_SYNTAX_NOSUCHOBJECT | Indicates that the agent does not support the object type that corresponds to the variable.
SNMP_SYNTAX_NOSUCHINSTANCE | Indicates that the object instance does not exist for the operation.
SNMP_SYNTAX_ENDOFMIBVIEW | Indicates the WinSNMP manager application is attempting to reference an object identifier that is beyond the end of the MIB tree that the agent supports.

The last three syntax types describe exception conditions under the SNMP version 2C(SNMPv2C) framework.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpGetVb function returns the variable name of the variable binding entry in the structure pointed to by the name parameter. It returns the variable's associated value in the structure pointed to by the value parameter.

On input, the SnmpGetVb function ignores the members of the smiOID and smiVALUE structures pointed to by the name and value parameters respectively. The Microsoft WinSNMP implementation overwrites the members if the function completes successfully.

Valid values for a WinSNMP manager application to use for the index parameter are as follows:

  • The return value from a call to the SnmpCountVbl function
  • The error index field of an SNMP_PDU_RESPONSE protocol data unit (PDU) returned by a call to the SnmpRecvMsg function

The WinSNMP manager application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure pointed to by the name parameter. The application must also call the SnmpFreeDescriptor function to release resources allocated for the smiVALUE structure pointed to by the value parameter under the conditions following. If the value member is an smiOCTETS or an smiOID structure, the application must call SnmpFreeDescriptor to free the resources allocated for these structures. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpCountVbl, SnmpRecvMsg, SnmpFreeDescriptor, smiOID, smiVALUE, smiOCTETS


SnmpOidCompare

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpOidCompare function lexicographically compares two SNMP object identifiers, up to the length specified by the maxlen parameter.

SNMPAPI_STATUS SnmpOidCompare(
  smiLPCOID xOID,      // first object identifier to compare
  smiLPCOID yOID,      // second object identifier to compare
  smiUINT32 maxlen,    // maximum length to compare
  smiLPINT result      // result of comparison
);

Parameters

xOID
Pointer to the first smiOID object identifier to compare. The length of the object identifier can be zero.
yOID
Pointer to the second smiOID object identifier to compare. The length of the object identifier can be zero.
maxlen
If not equal to zero, specifies the number of subidentifiers to compare. This parameter must be less than MAXOBJIDSIZE: 128 subidentifiers, the maximum number of components in an object identifier. For additional information, see the following Remarks section.
result
Pointer to an integer variable to receive the result of the comparison. The variable can receive one of the following results.
Result | Meaning
Greater than 0 | xOID is greater than yOID
Equal to 0 | xOID equals yOID
Less than 0 | xOID is less than yOID

For additional comparison conditions, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | One or both of the xOID and yOID parameters is invalid.
SNMPAPI_SIZE_INVALID | The maxlen parameter is invalid. The parameter size is greater than MAXOBJIDSIZE.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP manager application can call the SnmpOidCompare function to determine whether two object identifiers have common prefixes.

If the maxlen parameter is not equal to zero, and not greater than MAXOBJIDSIZE, the value of maxlen sets the upper limit for the number of subidentifiers to compare. The maximum number of subidentifiers that the SnmpOidCompare function compares defaults to whichever is the smallest number — the maxlen parameter, or the len member of one of the smiOID structures pointed to by the xOID and yOID parameters.

If the maxlen parameter is equal to zero, the maximum number of subidentifiers that the SnmpOidCompare function compares defaults to the number that is the smaller of the len members of the two smiOID structures.

The value of the result parameter will indicate that xOID equals yOID if the two smiOID structures are lexicographically equal and one of the following occurs:

  • SnmpOidCompare compares a maxlen number of subidentifiers.
  • SnmpOidCompare compares the maximum number of subidentifiers, and the len members of both smiOID structures are equal, but less than the maxlen parameter.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, smiOID


SnmpOidCopy

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpOidCopy function copies an SNMP object identifier, allocating any necessary memory for the copy.

SNMPAPI_STATUS SnmpOidCopy(
  smiLPCOID srcOID,      // source object identifier
  smiLPOID dstOID        // destination object identifier
);

Parameters

srcOID
Pointer to an smiOID structure to copy.
dstOID
Pointer to an smiOID structure to receive a copy of the object identifier specified by the srcOID parameter.

Return Values

If the function succeeds, the return value is the number of subidentifiers in the copied object identifier. This number is also the value of the len member of the smiOID structure pointed to by the dstOID parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | The srcOID parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

On input, the SnmpOidCopy function ignores the members of the smiOID structure pointed to by the dstOID parameter. The Microsoft WinSNMP implementation overwrites the smiOID members if the function completes successfully.

The WinSNMP manager application must call the SnmpFreeDescriptor function to enable the implementation to free resources allocated for the ptr member of the smiOID structure pointed to by the dstOID parameter. For additional information, see WinSNMP Data Management Concepts and Freeing WinSNMP Descriptors.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOID


SnmpOidToStr

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpOidToStr function converts the internal binary representation of an SNMP object identifier to its dotted numeric string format, for example, to "1.2.3.4.5.6".

SNMPAPI_STATUS SnmpOidToStr(
  smiLPCOID srcOID,  // object identifier to convert
  smiUINT32 size,    // buffer size for string
  LPSTR string       // pointer to buffer for converted string
                     // object identifier
);

Parameters

srcOID
Pointer to an smiOID structure with an object identifier to convert.
size
Specifies the size, in bytes, of the buffer indicated by the string parameter.
string
Pointer to a buffer to receive the converted string object identifier that specifies the SNMP management entity.

Return Values

If the function succeeds, the return value is the length, in bytes, of the string that the WinSNMP manager application writes to the string parameter. The return value includes a null-terminating byte. This value may be less than or equal to the value of the size parameter, but it may not be greater.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | The srcOID parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

It is recommended that a WinSNMP manager application specify, with the size parameter, a string buffer of MAXOBJIDSTRSIZE length (1408 bytes). This ensures that the output buffer is large enough to hold the converted string. Because the converted string is usually less than MAXOBJIDSTRSIZE, the WinSNMP manager application can copy the converted string to a smaller buffer. The WinSNMP manager application can then reuse or free the memory that it allocated for the initial buffer. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToOid, smiOID


SnmpOpen

[This is preliminary documentation and subject to change.]

The SnmpOpen function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP manager application. This WinSNMP function enables the implementation to allocate and initialize memory, resources, data structures, and communications mechanisms. The SnmpOpen function returns a handle to the new WinSNMP session.

HSNMP_SESSION SnmpOpen(
  HWND hWnd,      // handle to the notification window
  UINT wMsg       // window notification message number
);

Parameters

hWnd
Handle to a window of the WinSNMP manager application to notify when an asynchronous request completes, or when trap notification occurs.
wMsg
Specifies an unsigned integer that identifies the notification message to send to the WinSNMP manager application window.

Return Values

If the function succeeds, the return value is a handle that identifies the WinSNMP session that the implementation opens for the calling manager application.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_HWND_INVALID | The hWnd parameter is not a valid window handle.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpOpen function returns a unique handle to each open WinSNMP session within the calling WinSNMP manager application. The application must use the session handle that SnmpOpen returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation. When the implementation allocates resources to an individual session, it performs an orderly release of resources in response to a call to SnmpClose for the session.

The SnmpOpen function passes to the implementation the handle to an application window and a notification message identifier. If the wParam component of the notification message specified by the wMsg parameter is equal to zero, the WinSNMP manager application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpOpen. If the wParam parameter of the notification message is not equal to zero, it represents a WinSNMP error code. The error code applies to the PDU identified by the request identifier in the lParam parameter of the notification message.

One WinSNMP manager application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP manager application specify a unique wMsg parameter for each session.

It is recommended that a WinSNMP manager application call the SnmpClose function once for each session that the implementation opens as a result of a call to the SnmpOpen function. If a WinSNMP manager application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources. The implementation treats one SnmpCleanup call as if it were a series of SnmpClose calls, one call for each session the implementation opens as a result of a call to SnmpOpen.

For additional information, see WinSNMP Sessions.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpRecvMsg


SnmpRecvMsg

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpRecvMsg function retrieves the results of a completed asynchronous request submitted by a call to the SnmpSendMsg function, in the form of an SNMP message. The SnmpRecvMsg function also returns outstanding trap data and notifications registered for a WinSNMP session.

SNMPAPI_STATUS SnmpRecvMsg(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  LPHSNMP_ENTITY srcEntity,   // handle to the source entity
  LPHSNMP_ENTITY dstEntity,   // handle to the target entity
  LPHSNMP_CONTEXT context,    // handle to the context
  LPHSNMP_PDU PDU             // handle to the PDU
);

Parameters

session
Handle to the WinSNMP session.
srcEntity
Pointer to a variable that receives a handle to the entity that sends the message. Note that the srcEntity parameter to the SnmpRegister function specifies a handle to the management entity that requests traps.
dstEntity
Pointer to a variable that receives a handle to the entity that receives the message. Note that the dstEntity parameter to the SnmpRegister function specifies a handle to the management entity that sends traps.
context
Pointer to a variable that receives a handle to the context, which is a set of managed object resources. The entity specified by the srcEntity parameter issues the message from this context.
PDU
Pointer to a variable that receives a handle to the protocol data unit (PDU) component of the message.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS, and the output parameters contain the values indicated in the preceding parameter descriptions.

If the function fails, the return value is SNMPAPI_FAILURE. If the function fails with an extended error code that indicates a network transport layer error, that is, one that begins with SNMPAPI_TL_, the output parameters also contain the values indicated preceding to enable the WinSNMP manager application to recover gracefully.

To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_NOOP | The specified session has no messages in its queue at this time.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_NOT_SUPPORTED | The network transport layer does not support the SNMP protocol.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_TL_RESOURCE_ERROR | A resource error occurred in the network transport layer.
SNMPAPI_TL_UNDELIVERABLE | The entity specified by the dstEntity parameter is unavailable.
SNMPAPI_TL_SRC_INVALID | The entity specified by the srcEntity parameter was not initialized.
SNMPAPI_TL_INVALID_PARAM | A network transport layer function call received an invalid input parameter.
SNMPAPI_TL_PDU_TOO_BIG | The PDU is too large for the network transport layer to send or receive.
SNMPAPI_TL_OTHER | An undefined network transport layer error occurred.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

The SnmpOpen function passes an application window handle and notification message identifier to the Microsoft WinSNMP implementation. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP manager application must call the SnmpRecvMsg function with the session handle returned by SnmpOpen to retrieve an incoming protocol data unit (PDU). For additional information, see About SNMP Messages.

The SnmpRecvMsg function instantiates four objects and allocates their resources: two entity handles, a context handle, and a PDU handle. The handle to the variable bindings list component of the returned PDU is not instantiated until the WinSNMP manager application calls the SnmpGetPduData function. When it no longer needs the resources SnmpRecvMsg returns, the WinSNMP manager application must free the individual resources using the WinSNMP function that corresponds to the resource. For additional information, see SnmpFreePdu, SnmpFreeEntity, and SnmpFreeContext.

When the implementation receives traps from an entity operating under the SNMP version 1 framework (SNMPv1), it translates the traps to the SNMP version 2C (SNMPv2C) format. Therefore, when SnmpRecvMsg delivers a trap it is always in the SNMPv2C format. For additional information, see Translating Traps from SNMPv1 to SNMPv2C and WinSNMP Programming Tasks.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreePdu, SnmpFreeEntity, SnmpFreeContext, SnmpSendMsg, SnmpRegister, SnmpGetPduData


SnmpRegister

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpRegister function registers or unregisters a WinSNMP manager application for trap and notification reception. The application can register and receive traps and notifications, or unregister and disable traps and notifications.

A WinSNMP manager application can register or unregister for one type of trap or notification, or for all traps and notifications, depending on the value of the notification parameter.

SNMPAPI_STATUS SnmpRegister(
  HSNMP_SESSION session,   // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,  // handle to the entity that will
                           // receive traps
  HSNMP_ENTITY dstEntity,  // handle to the entity that will
                           // send traps
  HSNMP_CONTEXT context,   // handle to the context
  smiLPCOID notification,  // trap-matching sequence
  smiUINT32 state          // flag for trap reception
);

Parameters

session
Handle to the WinSNMP session that is registering or unregistering for traps and notifications.
srcEntity
Handle to the management entity that is the source of the trap or notification registration request. This entity, acting in an SNMP manager role, will receive the trap or notification.

If this parameter is NULL, the Microsoft WinSNMP implementation registers or unregisters all sources of trap and notification requests.

Note that the srcEntity parameter to the SnmpRecvMsg function receives a handle to the management entity that sends traps.

dstEntity
Handle to the management entity that is the recipient of the trap or notification registration request. This entity, acting in an SNMP agent role, will send the trap or notification.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP manager application for traps and notifications from all management entities.

Note that the dstEntity parameter to the SnmpRecvMsg function receives a handle to the management entity that requests traps.

context
Handle to the context, which is a set of managed object resources.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP manager application for traps and notifications for every context.

notification
Pointer to an smiOID structure that contains the pattern-matching sequence for one type of trap or notification. The implementation uses this sequence to identify the type of trap or notification for which the WinSNMP manager application is registering or unregistering. For additional information, see the following Remarks section.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP manager application for all traps and notifications from the management entity or entities specified by the dstEntity parameter.

state
Specifies an unsigned long integer variable that indicates whether the WinSNMP manager application is registering to receive traps and notifications, or if it is unregistering. This parameter should be equal to one of the following values, but if it contains a different value, the implementation registers the application.
Value | Meaning
SNMPAPI_OFF | Disable traps and notifications.
SNMPAPI_ON | Register to receive traps and notifications.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OID_INVALID | The notification parameter is invalid.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_IN_USE | The trap port is not available.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

If a WinSNMP manager application passes NULL in a call to the SnmpRegister function in the srcEntity, dstEntity, context, or notification parameters, the implementation does not use that parameter to filter traps and notifications from reaching the WinSNMP manager application.

If a WinSNMP manager application registers to receive a specific type of trap or notification, it must define an object identifier, that is, an smiOID structure, that corresponds to that type of trap. The notification parameter must point to this structure. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," defines trap and notification object identifiers. For additional information, see Translating Traps from SNMPv1 to SNMPv2C.

The implementation uses the value of the notification parameter as a pattern to match against received traps and notifications. For example, if the WinSNMP manager application passes n number of subidentifiers in the notification parameter, and the first n subidentifiers in a received trap match all the passed subidentifiers, then the trap object identifier is a match. If a received trap has fewer subidentifiers than n, the object identifier does not match. If there is a match, the implementation sends the trap or notification to the WinSNMP manager application.

If any or all of the dstEntity, srcEntity, or context parameters are NULL, the implementation may need to allocate resources on a subsequent call to the SnmpRecvMsg function, for that function's corresponding parameters. When the WinSNMP manager application no longer needs the resources SnmpRecvMsg returns, the application must free the individual resources with the function that corresponds to the resource. For additional information, see SnmpFreeEntity and SnmpFreeContext.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpOpen, SnmpRecvMsg, SnmpFreeEntity, SnmpFreeContext


SnmpSendMsg

[This is preliminary documentation and subject to change.]

A WinSNMP manager application calls the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit an SNMP protocol data unit (PDU), in the form of an SNMP message. The WinSNMP manager application specifies a source entity, a destination entity, and a context for the request.

If a WinSNMP manager application expects a PDU in response to a SnmpSendMsg request, it must retrieve the PDU. To do this, the application must call the SnmpRecvMsg function using the session handle returned by SnmpOpen.

SNMPAPI_STATUS SnmpSendMsg(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,     // handle to the source entity
  HSNMP_ENTITY dstEntity,     // handle to the target entity
  HSNMP_CONTEXT context,      // handle to the context
  HSNMP_PDU PDU               // handle to the PDU
);

Parameters

session
Handle to the WinSNMP session.
srcEntity
Handle to the management entity that initiates the request to send the SNMP message.
dstEntity
Handle to the target management entity that receives the request to send the SNMP message.
context
Handle to the context, (a set of managed object resources), that the target management entity controls.
PDU
Handle to the protocol data unit that contains the SNMP operation request.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The PDU parameter is invalid.
SNMPAPI_OPERATION_INVALID | The operation specified in the PDU_type field of the PDU is inappropriate for the destination entity.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_NOT_SUPPORTED | The network transport layer does not support the SNMP protocol.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_TL_RESOURCE_ERROR | A resource error occurred in the network transport layer.
SNMPAPI_TL_SRC_INVALID | The entity specified by the srcEntity parameter was not initialized.
SNMPAPI_TL_INVALID_PARAM | A network transport layer function call received an invalid input parameter.
SNMPAPI_TL_PDU_TOO_BIG | The PDU is too large for the network transport layer to send or receive.
SNMPAPI_TL_OTHER | An undefined network transport layer error occurred.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

The SnmpSendMsg function executes asynchronously and therefore returns immediately.

The implementation notifies the WinSNMP manager application when the asynchronous request is completed. The implementation does this by sending a notification message to the window specified by the wMsg and hWnd parameters, respectively, in the initial call to SnmpOpen for the session. When the application window receives the notification message, the WinSNMP manager application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpOpen.

When a WinSNMP manager application calls the SnmpSendMsg function, the implementation determines which network transport protocol and SNMP version framework to use to complete the transmission request. The implementation determines this by matching its capabilities with properties associated with the requesting session and with the target management entity. This information is available from values in the implementation's database.

If a WinSNMP manager application requests functionality that is available under the SNMP version 2C framework (SNMPv2C), but the target entity uses the SNMP version 1 framework (SNMPv1), the implementation attempts to translate the request to SNMPv1. To do this, the implementation uses the procedures defined in RFC1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework." If translation is not possible, SnmpSendMsg fails with the extended error code SNMPAPI_OPERATION_INVALID.

For additional information, see WinSNMP Programming Tasks and About SNMP Messages.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpOpen, SnmpRecvMsg


SnmpSetPduData

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetPduData function updates selected data fields in the specified SNMP protocol data unit (PDU).

SNMPAPI_STATUS SnmpSetPduData(
  HSNMP_PDU PDU,                 // handle to the PDU
  const smiINT *PDU_type,        // pointer to the PDU type
  const smiINT32 *request_id,    // pointer to the PDU request
                                 // identifier
  const smiINT *non_repeaters,   // valid only for an
                                 // SNMP_PDU_GETBULK request
  const smiINT *max_repetitions, // valid only for an
                                 // SNMP_PDU_GETBULK request
  const HSNMP_VBL *varbindlist   // handle to variable bindings list
);

Parameters

PDU
Handle to an SNMP PDU.
PDU_type
Pointer to a variable with a value to update the PDU_type field of the specified PDU. This parameter can also be NULL.
request_id
Pointer to a variable with a value to update the request_id field of the specified PDU. This parameter can also be NULL.
non_repeaters
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter points to a variable with a value to update the non_repeaters field of the specified PDU. The Microsoft WinSNMP implementation ignores this parameter for other PDU types. This parameter can also be NULL.
max_repetitions
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter points to a variable with a value to update the max_repetitions field of the specified PDU. The implementation ignores this parameter for other PDU types. This parameter can also be NULL.
varbindlist
Pointer to a variable with a value that updates the handle to the variable bindings list field of the specified PDU. This parameter can also be NULL.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_VBL_INVALID | The variable bindings list is invalid.
SNMPAPI_NOOP | All input parameters are NULL. The SNMP operation was not performed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

All parameters of the SnmpSetPduData function are required. However, all parameters, except the PDU parameter, can be NULL. If the WinSNMP manager application passes NULL in a parameter, SnmpSetPduData does not update the corresponding field in the PDU. Because SnmpSetPduData passes parameters as pointers to values, an application can still update a PDU field with NULL.

The value of one PDU field can be valid alone, but may be invalidated in combination with values for other fields. The implementation validates the PDU and the other message elements when the manager application calls the SnmpSendMsg or the SnmpEncodeMsg functions. The implementation rejects invalid PDUs.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSendMsg, SnmpEncodeMsg


SnmpSetRetransmitMode

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetRetransmitMode function enables a WinSNMP manager application to set the retransmission mode. The Microsoft WinSNMP implementation uses the new retransmission mode to govern transmission time-outs and retransmission attempts on subsequent calls to the SnmpSendMsg function.

SNMPAPI_STATUS SnmpSetRetransmitMode(
  smiUINT32 nRetransmitMode  // new retransmission mode
);

Parameters

nRetransmitMode
Specifies a value for the new retransmission mode. This parameter must be one of the following values.
Value | Meaning
SNMPAPI_ON | The implementation executes the WinSNMP manager application's retransmission policy.
SNMPAPI_OFF | The implementation does not execute the WinSNMP manager application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_MODE_INVALID | The implementation does not support the requested retransmission mode.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

If a WinSNMP manager application sets the retransmission mode to SNMPAPI_OFF, the implementation does not initiate retransmission attempts for new SNMP communications operations. The new setting affects all subsequent calls to the SnmpSendMsg function, until the WinSNMP manager application sets the retransmission mode back to SNMPAPI_ON.

Note If the implementation returns the error SNMPAPI_MODE_INVALID to a call to SnmpSetRetransmitMode, the WinSNMP manager application must execute the retransmission policy.

For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSendMsg, SnmpRegister, SnmpGetRetransmitMode, SnmpGetTimeout, SnmpGetRetry


SnmpSetRetry

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetRetry function enables a WinSNMP manager application to change the retry count value for the retransmission of SNMP message requests. The retry count applies to calls that a WinSNMP manager application makes to the SnmpSendMsg function for a specified management entity. The Microsoft WinSNMP implementation stores the value in a database.

SNMPAPI_STATUS SnmpSetRetry(
  HSNMP_ENTITY hEntity,    // destination management entity
  smiUINT32 nPolicyRetry   // new retry count value for database
);

Parameters

hEntity
Handle to the destination management entity of interest.
nPolicyRetry
Specifies a new value for the retry count for the management entity. This value replaces the value currently stored in the implementation's database.

If this parameter is equal to zero, and the current retransmission mode is equal to SNMPAPI_ON, the implementation selects a value for the retry count. The implementation uses this value when it executes the WinSNMP manager application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSetRetransmitMode, SnmpGetRetry, SnmpGetRetransmitMode


SnmpSetTimeout

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetTimeout function enables a WinSNMP manager application to change the time-out value for the transmission of SNMP message requests. The time-out value applies to calls that a WinSNMP manager application makes to the SnmpSendMsg function for a specified management entity. The Microsoft WinSNMP implementation stores the value in a database.

SNMPAPI_STATUS SnmpSetTimeout(
  HSNMP_ENTITY hEntity,        // destination management entity
  smiTIMETICKS nPolicyTimeout  // new time-out value for database
);

Parameters

hEntity
Handle to the destination management entity of interest.
nPolicyTimeout
Specifies a new time-out value, in hundredths of a second, for the management entity. This value replaces the value currently stored in the implementation's database.

If this parameter is equal to zero, and the current retransmission mode is equal to SNMPAPI_ON, the implementation selects a time-out value. The implementation uses this time-out value when it executes the WinSNMP manager application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

For additional information, see About Retransmission and Managing the Retransmission Policy.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpGetTimeout, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpSetTranslateMode

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetTranslateMode function enables a WinSNMP manager application to change the entity and context translation mode. The entity and context translation mode affects the interpretation and return of WinSNMP input and output string parameters.

SNMPAPI_STATUS SnmpSetTranslateMode(
  smiUINT32 nTranslateMode  // new entity/context translation mode
);

Parameters

nTranslateMode
Specifies a value for the new entity and context translation mode. This parameter must be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The Microsoft WinSNMP implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_MODE_INVALID | The implementation does not support the requested translation mode.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The new entity and context translation mode affects subsequent calls to the SnmpStrToEntity, SnmpStrToContext, SnmpContextToStr, and SnmpEntityToStr functions. The WinSNMP manager application can change the entity and context translation mode again by making another call to SnmpSetTranslateMode with a different nTranslateMode value.

For additional information, see Setting the Entity and Context Translation Mode.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToContext, SnmpStrToEntity, SnmpContextToStr, SnmpEntityToStr, SnmpGetTranslateMode


SnmpSetVb

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpSetVb function changes variable binding entries in a variable bindings list. This function also appends new variable binding entries to an existing variable bindings list.

SNMPAPI_STATUS SnmpSetVb(
  HSNMP_VBL vbl,     // handle to the variable bindings list
  smiUINT32 index,   // position of the variable binding entry
                     // in the list
  smiLPCOID name,    // pointer to the variable name portion
                     // of the entry
  smiLPCVALUE value  // pointer to the variable value portion
                     // of the entry
);

Parameters

vbl
Handle to the variable bindings list to update.
index
Specifies an unsigned long integer variable that contains the position of the variable binding entry, within the variable bindings list, if this is an update operation. If this is an append operation, this parameter must be equal to zero.
name
Pointer to an smiOID structure that represents the name of the variable to append or change. This parameter cannot be NULL.
value
Pointer to an smiVALUE structure. The structure contains the value associated with the variable specified by the name parameter.

Return Values

If the function succeeds, the return value is the position of the updated or appended variable binding entry in the variable bindings list. For additional information, see the following Remarks section.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_OID_INVALID | The name parameter is invalid.
SNMPAPI_SYNTAX_INVALID | The syntax member of the structure pointed to by the value parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Valid values for the index parameter range from zero to n. The value zero indicates an append operation. The value n is the total number of variable binding entries in the variable bindings list. A WinSNMP manager application should call the SnmpCountVbl function before it calls SnmpSetVb to obtain the total number of variable binding entries.

If the function successfully performs an update operation, the return value equals the value of the index parameter. If the function appends a variable binding entry, the return value is n + 1.

If the name parameter is not NULL, but the value parameter is NULL, the Microsoft WinSNMP implementation initializes the new variable binding entry with the value member set to NULL and with the syntax member set to SNMP_SYNTAX_NULL.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpCountVbl, smiOID, smiVALUE


SnmpStartup

[This is preliminary documentation and subject to change.]

The SnmpStartup function notifies the Microsoft WinSNMP implementation that the WinSNMP manager application requires the implementation's services. The WinSNMP SnmpStartup function enables the implementation to initialize and to return to the application the version of the Windows SNMP Manager Application Programming Interface (WinSNMP Manager API), the level of SNMP communications that the implementation supports, and the implementation's default translation and retransmission modes.

Note A WinSNMP manager application must call the SnmpStartup function successfully before it calls any other WinSNMP function.

SNMPAPI_STATUS SnmpStartup(
  smiLPUINT32 nMajorVersion,   // major version number of the
                               // WinSNMP API
  smiLPUINT32 nMinorVersion,   // minor version number of the
                               // WinSNMP API
  smiLPUINT32 nLevel,          // level of SNMP the implementation
                               // supports
  smiLPUINT32 nTranslateMode,  // default entity/context translation
                               // mode
  smiLPUINT32 nRetransmitMode  // default retransmission mode
);

Parameters

nMajorVersion
Pointer to an unsigned long integer variable to receive the major version number of the WinSNMP Manager API that the implementation supports.
nMinorVersion
Pointer to an unsigned long integer variable to receive the minor version number of the WinSNMP Manager API that the implementation supports.
nLevel
Pointer to an unsigned long integer variable to receive the highest level of SNMP communications the implementation supports. Upon successful return, this parameter can be one of the following values.
Value | Meaning
SNMPAPI_NO_SUPPORT | Level 0: Support for message encoding and decoding only.
SNMPAPI_V1_SUPPORT | Level 1: Support for Level 0 communications, as well as interaction with SNMP agent entities operating under the SNMP version 1 framework (SNMPv1).
SNMPAPI_V2_SUPPORT | Level 2: Support for Level 1 communications, as well as interaction with SNMP agent entities operating under the SNMP version 2C framework (SNMPv2C).

nTranslateMode
Pointer to an unsigned long integer variable to receive the default translation mode in effect for the implementation. The translation mode applies to the implementation's interpretation of the entity parameter that the WinSNMP manager application passes to the SnmpStrToEntity function. The translation mode also applies to the string parameter that the WinSNMP manager application passes to the SnmpStrToContext function. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings.

For additional information, see Setting the Entity and Context Translation Mode.

nRetransmitMode
Pointer to an unsigned long integer variable to receive the default retransmission mode in effect for the implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_OFF | The implementation is not executing the retransmission policy of the WinSNMP manager application.
SNMPAPI_ON | The implementation is executing the retransmission policy of the WinSNMP manager application.

For additional information, see About Retransmission.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS, and the parameters contain appropriate values, as indicated in the preceding parameter descriptions.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors. For additional information, see the Remarks section that follows.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP manager application must call the SnmpStartup function successfully at least once, before it calls any other WinSNMP function. If a WinSNMP manager application does call another WinSNMP function, before it successfully calls SnmpStartup, the implementation returns the error SNMPAPI_NOT_INITIALIZED.

The WinSNMP manager application can call SnmpGetLastError for error information, or retry SnmpStartup if a call to the SnmpStartup function fails. When SnmpStartup returns SNMPAPI_FAILURE, and a subsequent call to SnmpGetLastError returns SNMP_ALLOC_ERROR, the WinSNMP manager application can elect to wait. It can retry the call to SnmpStartup when the implementation has adequate free resources.

A WinSNMP manager application can call SnmpStartup multiple times. For example, it may need to retry the function call for the reasons discussed preceding. A WinSNMP manager application must also call SnmpCleanup at least once, as the last WinSNMP function call before it terminates. Multiple SnmpStartup calls do not require multiple SnmpCleanup calls.

For additional information, see Levels of SNMP Support and About SNMP Versions.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToEntity, SnmpStrToContext, SnmpCleanup


SnmpStrToContext

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpStrToContext function returns a handle to SNMP context information that is specific to the Microsoft WinSNMP implementation. The handle is a valid value that a WinSNMP manager application can use as the context parameter in a call to the SnmpSendMsg and SnmpRegister functions.

HSNMP_CONTEXT SnmpStrToContext(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  smiLPCOCTETS string     // pointer to a string structure
);

Parameters

session
Handle to the WinSNMP session.
string
Pointer to an smiOCTETS structure that contains a string to interpret. The string can identify a collection of managed objects, or it can be a community string.

The current setting of the entity and context translation mode determines the way SnmpStrToContext interprets the input string structure as shown in the following table.
Entity/Context Translation Mode | Meaning
SNMPAPI_TRANSLATED | The implementation interprets the string parameter as a user-friendly name for a collection of managed objects. The implementation translates the name into its SNMPv1 or SNMPv2C components using the implementation's database.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets the string parameter as a literal SNMP community string.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets the string parameter as a literal SNMP community string.

Return Values

If the function succeeds, the return value is a handle to the context of interest.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_CONTEXT_INVALID | The string parameter format is invalid. For example, the len member or the ptr member of the smiOCTETS structure pointed to by the string parameter is NULL.
SNMPAPI_CONTEXT_UNKNOWN | The value referenced in the string parameter does not exist.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the manner in which SnmpStrToContext interprets the input string structure. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP manager application must call the SnmpFreeContext function to release the context handle allocated by the SnmpStrToContext function. For additional information about releasing resources, see WinSNMP Data Management Concepts.

The WinSNMP manager application should free the memory associated with the ptr member of the smiOCTETS structure pointed to by the string parameter. This is because the application defines and allocates the resources. For example, if the application allocated resources with a call to the GlobalAlloc function, it should use the GlobalFree function to deallocate the resources. For additional information, see Freeing WinSNMP Descriptors.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpSendMsg, SnmpRegister, SnmpFreeDescriptor, SnmpFreeContext, smiOCTETS


SnmpStrToEntity

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpStrToEntity function returns a handle to information about an SNMP management entity that is specific to the Microsoft WinSNMP implementation.

HSNMP_ENTITY SnmpStrToEntity(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  LPCSTR string           // pointer to a string that identifies
                          // the entity
);

Parameters

session
Handle to the WinSNMP session.
string
Pointer to a null-terminated string that identifies the SNMP management entity of interest. The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string as follows.
Entity/Context Translation Mode | Meaning
SNMPAPI_TRANSLATED | The implementation interprets the string parameter as a user-friendly name. The implementation translates the name into its SNMPv1 or SNMPv2C components using the implementation's database.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets the string parameter as a literal SNMP transport address.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets the string parameter as a literal SNMP transport address.

Return Values

If the function succeeds, the return value is a handle to the SNMP management entity of interest.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_UNKNOWN | The entity string is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string that identifies the management entity of interest. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP manager application should call the SnmpFreeEntity function to release the entity handle allocated by the SnmpStrToEntity function. For additional information, see WinSNMP Data Management Concepts.

The SnmpStrToEntity function returns a valid entity handle that a WinSNMP manager application can use as the srcEntity or the dstEntity parameter in multiple WinSNMP functions. These functions include the SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, and SnmpDecodeMsg functions.

The implementation returns the current entity and context translation mode in the nTranslateMode parameter of the SnmpStartup function. A WinSNMP manager application can change the setting of the entity and context translation mode with a call to the SnmpSetTranslateMode function.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeEntity, SnmpSetTranslateMode, SnmpStartup, SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, SnmpDecodeMsg


SnmpStrToOid

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpStrToOid function converts the dotted numeric string format of an SNMP object identifier, for example, "1.2.3.4.5.6", to its internal binary representation.

SNMPAPI_STATUS SnmpStrToOid(
  LPCSTR string,      // string object identifier to convert
  smiLPOID dstOID     // object identifier internal representation
);

Parameters

string
Pointer to a null-terminated object identifier string to convert.
dstOID
Pointer to an smiOID structure that receives the converted value.

Return Values

If the function succeeds, the return value is the number of subidentifiers in the converted object identifier. This number is also the value of the len member of the smiOID structure pointed to by the dstOID parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | The string parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The WinSNMP manager application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure pointed to by the dstOID parameter. On input, SnmpFreeDescriptor ignores the members of this smiOID structure. The Microsoft WinSNMP implementation overwrites the smiOID members if the function completes successfully.

The SnmpStrToOid function fails and returns the SNMPAPI_OID_INVALID error code if the string parameter meets one of the following conditions:

  • Is not null-terminated.
  • Is not the textual form of a valid object identifier.
  • Is insufficient in length; all object identifiers must have two subidentifiers.
  • Exceeds the MAXOBJIDSTRSIZE of 1408 bytes.

For additional information, see WinSNMP Data Management Concepts and Freeing WinSNMP Descriptors.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOID


WinSNMP Structures

[This is preliminary documentation and subject to change.]

The WinSNMP Manager API functions use the following structures:


smiCNTR64

[This is preliminary documentation and subject to change.]

The WinSNMP smiCNTR64 structure contains a 64-bit unsigned integer value. The structure represents a 64-bit counter.

typedef struct {
    smiUINT32   hipart;    // high-order 32 bits
    smiUINT32   lopart;    // low-order 32 bits
} smiCNTR64, *smiLPCNTR64;

Members

hipart
Specifies the high-order 32 bits of the counter.
lopart
Specifies the low-order 32 bits of the counter.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.

See Also

WinSNMP Manager API Overview, WinSNMP Structures, SnmpGetVb, smiVALUE


smiOCTETS

[This is preliminary documentation and subject to change.]

The WinSNMP smiOCTETS structure passes context strings to multiple WinSNMP functions. The structure also describes and receives encoded SNMP messages.

The smiOCTETS structure contains a pointer to an SNMP octet string of variable length. The structure can be a member of the smiVALUE structure.

typedef struct {
    smiUINT32   len;    // number of bytes in the octet string
    smiLPBYTE   ptr;    // pointer to an octet string
} smiOCTETS, *smiLPOCTETS;

Members

len
Specifies an unsigned long integer value that indicates the number of bytes in the octet string array pointed to by the ptr member.
ptr
Pointer to a byte array that contains the octet string of interest. A NULL-terminating byte is not required.

Remarks

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS structures. The WinSNMP manager application should not free memory that the implementation allocates for the ptr member of an smiOCTETS structure. Instead, the application must call the SnmpFreeDescriptor function to free the memory.

Because the WinSNMP manager application allocates memory for input descriptor objects with variable lengths, it must free that memory. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.

See Also

WinSNMP Manager API Overview, WinSNMP Structures, SnmpStrToContext, SnmpContextToStr, SnmpEncodeMsg, SnmpDecodeMsg, SnmpFreeDescriptor, smiVALUE


smiOID

[This is preliminary documentation and subject to change.]

The WinSNMP smiOID structure passes object identifiers to multiple WinSNMP functions. The structure also receives the variable name of a variable binding entry in a call to the SnmpGetVb function.

The smiOID structure contains a pointer to a variable length array of a named object's subidentifiers. The structure can be a member of the smiVALUE structure.

typedef struct {
    smiUINT32     len;    // number of array elements
    smiLPUINT32   ptr;    // pointer to an array of subidentifiers
} smiOID, *smiLPOID;

Members

len
Specifies an unsigned long integer value that indicates the number of elements in the array pointed to by the ptr member.
ptr
Pointer to an array of unsigned long integers that represent the object identifier's subidentifiers.

Remarks

In an smiOID structure, the format of the array pointed to by the ptr member is one subidentifier per array element. For example, the string "1.3.6.1" would be an array of four elements {1,3,6,1}.

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOID structures. The WinSNMP manager application should not free memory that the implementation allocates for the ptr member of an smiOID structure. Instead, the application must call the SnmpFreeDescriptor function to free the memory.

Because the WinSNMP manager application allocates memory for input descriptor objects with variable lengths, it must free that memory. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.

See Also

WinSNMP Manager API Overview, WinSNMP Structures, SnmpGetVb, SnmpStrToOid, SnmpOidToStr, SnmpOidCopy, SnmpOidCompare, SnmpFreeDescriptor, smiVALUE


smiVALUE

[This is preliminary documentation and subject to change.]

The WinSNMP smiVALUE structure describes the value associated with a variable name in a variable binding entry.

The syntax member of the smiVALUE structure contains a WinSNMP data type that indicates the type of data in the value member. The value member of the structure is the union of all possible WinSNMP data types.

typedef struct {                // smiVALUE portion of VarBind
   smiUINT32    syntax;         // Insert SNMP_SYNTAX_<type>
     union {
       smiINT    sNumber;       // SNMP_SYNTAX_INT
                                // SNMP_SYNTAX_INT32
       smiUINT32 uNumber;       // SNMP_SYNTAX_UINT32
                                // SNMP_SYNTAX_CNTR32
                                // SNMP_SYNTAX_GAUGE32
                                // SNMP_SYNTAX_TIMETICKS
       smiCNTR64 hNumber;       // SNMP_SYNTAX_CNTR64
       smiOCTETS string;        // SNMP_SYNTAX_OCTETS
                                // SNMP_SYNTAX_BITS
                                // SNMP_SYNTAX_OPAQUE
                                // SNMP_SYNTAX_IPADDR
                                // SNMP_SYNTAX_NSAPADDR
       smiOID    oid;           // SNMP_SYNTAX_OID
       smiBYTE   empty;         // SNMP_SYNTAX_NULL
                                // SNMP_SYNTAX_NOSUCHOBJECT
                                // SNMP_SYNTAX_NOSUCHINSTANCE
                                // SNMP_SYNTAX_ENDOFMIBVIEW
     } value;    // union
} smiVALUE, *smiLPVALUE;

Members

syntax
Specifies an unsigned long integer that indicates the syntax data type of the value member. This member can be only one of the types listed in the following table. For additional information, see WinSNMP Data Types and RFC 1902, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)."
Syntax data type | Meaning
SNMP_SYNTAX_INT | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_BITS | Indicates a variable that is an enumeration of named bits with non-negative, contiguous values, starting at zero.
SNMP_SYNTAX_OCTETS | Indicates an octet string variable that is binary or textual data.
SNMP_SYNTAX_NULL | Indicates a NULL value.
SNMP_SYNTAX_OID | Indicates an object identifier variable that is an assigned name with a maximum of 128 subidentifiers.
SNMP_SYNTAX_INT32 | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_IPADDR | Indicates a 32-bit Internet address variable.
SNMP_SYNTAX_CNTR32 | Indicates a counter variable that increases until it reaches a maximum value of (2^32) – 1.
SNMP_SYNTAX_GAUGE32 | Indicates a gauge variable that is a non-negative integer that can increase or decrease, but never exceed a maximum value.
SNMP_SYNTAX_TIMETICKS | Indicates a counter variable that measures the time in hundredths of a second, until it reaches a maximum value of (2^32) – 1. It is a non-negative integer that is relative to a specific timer event.
SNMP_SYNTAX_OPAQUE | This type provides backward compatibility, and should not be used for new object types. It supports the capability to pass arbitrary Abstract Syntax Notation One (ASN.1) syntax.
SNMP_SYNTAX_CNTR64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
SNMP_SYNTAX_UINT32 | Indicates a 32-bit unsigned integer variable.
SNMP_SYNTAX_NOSUCHOBJECT | Indicates that the agent does not support the object type that corresponds to the variable.
SNMP_SYNTAX_NOSUCHINSTANCE | Indicates that the object instance does not exist for the operation.
SNMP_SYNTAX_ENDOFMIBVIEW | Indicates the WinSNMP manager application is attempting to reference an object identifier that is beyond the end of the MIB tree that the agent supports.

The last three syntax types describe exception conditions under the SNMP version 2C (SNMPv2C) framework.

value
Specifies the union of all possible WinSNMP syntax data types, including the smiOID or smiOCTETS descriptor types.

Remarks

A WinSNMP manager application must check the syntax member of an smiVALUE structure to correctly dereference the value member. The value member can contain a simple scalar value or a non-scalar value like an smiOCTETS or an smiOID descriptor structure.

If the syntax member indicates that the value member is an smiOCTETS or an smiOID descriptor structure, the WinSNMP manager application must determine whether to free the resources allocated for the structure. The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS and smiOID structures. The application must call the SnmpFreeDescriptor function to free the memory for the ptr member of these structures.

Because the WinSNMP manager application allocates memory for input descriptors with variable lengths, it must free that memory. For additional information, see WinSNMP Data Management Concepts.

QuickInfo

Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.

See Also

WinSNMP Manager API Overview, WinSNMP Structures, smiOCTETS, smiOID, SnmpGetVb, SnmpCreateVbl, SnmpFreeDescriptor


Windows Networking (WNet)

Microsoft® Windows® provides the Windows networking (WNet) functions so that you can implement networking capabilities in your application without making allowances for a particular network provider or physical network implementation. The reason is that the WNet functions are network independent.


About Windows Networking

Applications can use the Windows networking functions to add and cancel network connections and to retrieve information about the current configuration of the network.

The following figure shows the structure of a typical network.

In the preceding figure, the hierarchy for Microsoft Windows NT Server resources is given in detail as Network provider #1. Network resources from other providers have different hierarchical systems. An application does not need information about the hierarchy before it begins to work with a network. It can proceed from the network root (that is, the topmost container resource) and retrieve information about the network's resources as the information is required.

Network resources that contain other resources are called containers. Container resources are in boxes in the preceding figure.

Resources that do not contain other resources are objects. Sharepoint #1 and Sharepoint #2 in the figure are objects. A sharepoint is an object that is accessible across the network, such as a printer or a shared directory.


WNet Functions

The following functions are used in Windows networking:

Connection Functions

WNetAddConnection
WNetAddConnection2
WNetAddConnection3
WNetCancelConnection
WNetCancelConnection2
WNetConnectionDialog
WNetConnectionDialog1
WNetDisconnectDialog
WNetDisconnectDialog1
WNetGetConnection
WNetGetUniversalName

Enumeration Functions

WNetCloseEnum
WNetEnumResource
WNetOpenEnum

Information Functions

WNetGetNetworkInformation
WNetGetLastError
WNetGetProviderName
WNetGetResourceInformation
WNetGetResourceParent

User Functions

WNetGetUser

Many of these functions use a NETRESOURCE structure.

The WNetAddConnection and WNetCancelConnection functions are supported for compatibility with Windows for Workgroups. However, new applications should use WNetAddConnection2 or WNetAddConnection3 and WNetCancelConnection2.


Windows Networking Operations

An application can use the WNet functions to browse, add, or cancel network connections anywhere in the hierarchy. A persistent connection is a network connection that Windows automatically restores when the user logs on. You can use the WNetAddConnection2 and WNetCancelConnection2 functions to control whether a network connection is persistent from one session to the next.

To find the default user name or the user name used to establish a network connection, use the WNetGetUser function.

In addition to using the WNet functions, processes can also use mailslots and named pipes to communicate with one another. For more information about these subjects, see Mailslots and Pipes.


Using Windows Networking

The WNet functions enable your application to query and control network connections directly or to give direct control of the network connections to the user. To use these functions, you must link to the multiple-provider router library (MPR.LIB). This section discusses how to use the network functions in your application.

  • Using the connections dialog box
  • Enumerating network resources
  • Adding a network connection
  • Assigning a drive to a share
  • Determining the location of a share
  • Retrieving the connection name
  • Retrieving the user name
  • Canceling a network connection
  • Retrieving network errors


Using the Connections Dialog Box

Windows NT Only

The WNetConnectionDialog function creates a dialog box that allows the user to browse and connect to network resources. Conversely, the WNetDisconnectDialog function creates a dialog box that allows the user to disconnect from network resources.

The following example shows how to use the WNetConnectionDialog function to create a dialog box that displays disk resources.

DWORD dwResult;

dwResult = WNetConnectionDialog(hwnd, RESOURCETYPE_DISK);

if(dwResult != NO_ERROR)
{
    // An application-defined error handler is demonstrated in the
    // section titled "Retrieving Network Errors."

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetConnectionDialog");
    return FALSE;
}


Enumerating Network Resources

Windows NT Only

To enumerate a network container resource, your application should pass the address of a NETRESOURCE structure to the WNetOpenEnum function. WNetOpenEnum creates a handle to the resource described by the NETRESOURCE structure. The application then passes this handle to the WNetEnumResource function, which returns information about the resource in the form of an array of NETRESOURCE structures. When the handle is no longer needed, the application can close it by calling the WNetCloseEnum function.

Your application can continue enumerating any container resource described in the array of NETRESOURCE structures retrieved by WNetEnumResource. If the dwUsage member of the NETRESOURCE structure is RESOURCEUSAGE_CONTAINER, the application can pass the address of that structure to WNetOpenEnum to open the container and continue the enumeration. If dwUsage is RESOURCEUSAGE_CONNECTABLE, the application can pass the structure's address to the WNetAddConnection2 function.

The following example illustrates an application-defined function (EnumerateFunc) that enumerates all the resources on a network. When calling this function, specify NULL for the pointer to the NETRESOURCE structure. When WNetOpenEnum receives the NULL pointer, it retrieves a handle to the root of the network. Whenever a NETRESOURCE structure retrieved by WNetEnumResource is RESOURCEUSAGE_CONTAINER, the EnumerateFunc function calls itself and uses a pointer to that structure in its call to WNetOpenEnum.

BOOL WINAPI EnumerateFunc(HWND hwnd,
                          HDC hdc,
                          LPNETRESOURCE lpnr)
{
    DWORD dwResult, dwResultEnum;
    HANDLE hEnum;
    DWORD cbBuffer = 16384;      // 16K is a good size
    DWORD cEntries = 0xFFFFFFFF; // enumerate all possible entries
    LPNETRESOURCE lpnrLocal;     // pointer to enumerated structures
    DWORD i;

    dwResult = WNetOpenEnum(RESOURCE_GLOBALNET,
        RESOURCETYPE_ANY,
        0,                 // enumerate all resources
        lpnr,              // NULL first time this function is called
        &hEnum);           // handle to resource

    if (dwResult != NO_ERROR) {

        // An application-defined error handler is demonstrated in the
        // section titled "Retrieving Network Errors."

        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetOpenEnum");
        return FALSE;
    }

    do {

        // Allocate memory for NETRESOURCE structures.

        lpnrLocal = (LPNETRESOURCE) GlobalAlloc(GPTR, cbBuffer);

        dwResultEnum = WNetEnumResource(hEnum, // resource handle
            &cEntries,               // defined locally as 0xFFFFFFFF
            lpnrLocal,               // LPNETRESOURCE
            &cbBuffer);              // buffer size

        if (dwResultEnum == NO_ERROR) {
            for(i = 0; i < cEntries; i++)
            {
                // Following is an application-defined function for
                // displaying contents of NETRESOURCE structures.

                DisplayStruct(hdc, &lpnrLocal[i]);

                //
                // If this NETRESOURCE is a container, call the function
                // recursively.

                if(RESOURCEUSAGE_CONTAINER ==
                        (lpnrLocal[i].dwUsage & RESOURCEUSAGE_CONTAINER))
                    if(!EnumerateFunc(hwnd, hdc, &lpnrLocal[i]))
                        TextOut(hdc, 10, 10,
                            "EnumerateFunc returned FALSE.", 29);

            }
        }

        else if (dwResultEnum != ERROR_NO_MORE_ITEMS) {
            NetErrorHandler(hwnd, dwResultEnum, (LPSTR)"WNetEnumResource");
            break;
        }
    }
    while(dwResultEnum != ERROR_NO_MORE_ITEMS);

    GlobalFree((HGLOBAL) lpnrLocal);

    dwResult = WNetCloseEnum(hEnum);

    if(dwResult != NO_ERROR) {
        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCloseEnum");
        return FALSE;
    }

    return TRUE;
}


Adding a Network Connection

Windows NT Only

To make a connection to a network resource described by a NETRESOURCE structure, an application can call the WNetAddConnection2 function, as shown in the following example.

DWORD dwResult;
NETRESOURCE nr;

dwResult = WNetAddConnection2(&nr, // NETRESOURCE from enumeration
    (LPSTR) NULL,             // no password
    (LPSTR) NULL,             // logged-in user
    CONNECT_UPDATE_PROFILE);  // update profile with connect info

if (dwResult == ERROR_ALREADY_ASSIGNED)
{
    TextOut(hdc, 10, 10, "Already connected to specified resource.", 40);
    return FALSE;
}

else if (dwResult == ERROR_DEVICE_ALREADY_REMEMBERED)
{
    TextOut(hdc, 10, 10,
        "Attempted reassignment of remembered device.", 44);
    return FALSE;
}
else if(dwResult != NO_ERROR)
{
    // An application-defined error handler is demonstrated in the
    // section titled "Retrieving Network Errors."

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetAddConnection2");
    return FALSE;
}

TextOut(hdc, 10, 10, "Connected to specified resource.", 32);

The WNetAddConnection function is supported for compatibility with earlier versions of Windows for Workgroups. For new applications, use WNetAddConnection2 or WNetAddConnection3.


Assigning a Drive to a Share

Windows NT Only

The following example demonstrates how to use the WNetAddConnection2 function to connect a drive letter to a remote share on a server.

To test the code sample, change the following lines to valid strings:

szUserName[32]    = "myUserName",
szPassword[32]    = "myPassword",
szLocalName[32]    = "Q:",
szRemoteName[MAX_PATH] = "\\\\products2\\relsys";

Add the file to a Windows Consol App project called AddConn2 and link the library MPR.LIB to the compiler list of libraries. Then, run the file AddConn2.EXE after you compile the following program.

#include <windows.h>
#include <stdio.h>
#include <winnetwk.h>

void main()
{
NETRESOURCE nr;
DWORD res;
TCHAR szUserName[32] = "MyUserName",
    szPassword[32] = "MyPassword",
    szLocalName[32] = "Q:",
    szRemoteName[MAX_PATH] = "\\\\products2\\relsys";

nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = (LPTSTR) &szLocalName;
nr.lpRemoteName = (LPTSTR) &szRemoteName;
nr.lpProvider = NULL;

res = WNetAddConnection2(&nr, (LPTSTR) &szPassword, (LPTSTR) &szUserName, FALSE);

if(res == NO_ERROR)
  printf("Connection added \n", szRemoteName);
else
  printf("Error: %ld\n", res);
  return;
}


Determining the Location of a Share

Windows NT Only

The following example demonstrates how to use the WNetGetUniversalName function to determine the location of a share file on a redirected drive.

Name the code sample GetUni.cpp and add it to a Windows Consol App project called GetUni and link the libraries SHELL32.LIB, MPR.LIB, and NETAPI32.LIB to the compiler list of libraries.

Then from the command prompt, change to the GetUni directory and after compiling GetUni.cpp, run the file GetConn.EXE followed by a drive letter and colon like this:

GetUni H:\

/*
GetUni.cpp  code sample
*/
#define  STRICT
#include <windows.h>
#include <stdio.h>

#define BUFFSIZE = 1000

void main( int argc, char *argv[] )
{
DWORD cbBuff = 1000  //Size of Buffer
  TCHAR szBuff[1000];    //Buffer to receive information
  REMOTE_NAME_INFO  * prni = (REMOTE_NAME_INFO *)   &szBuff;
  //Pointers to head of buffer
  UNIVERSAL_NAME_INFO * puni = (UNIVERSAL_NAME_INFO *) &szBuff;
  DWORD res;

  if((argc < 2) | (lstrcmp(argv[1], "/?") == 0))
  {
    printf("Syntax:  GetUni DrivePathAndFilename\n"
         "Example: GetUni U:\\WINNT\\SYSTEM32\\WSOCK32.DLL\n");
    return;
  }

  //Call WNetGetUniversalName using UNIVERSAL_NAME_INFO_LEVEL option
  printf("Call WNetGetUniversalName using UNIVERSAL_NAME_INFO_LEVEL.\n");
  if((res = WNetGetUniversalName((LPTSTR)argv[1],
   UNIVERSAL_NAME_INFO_LEVEL,
   (LPVOID) &szBuff, //Structure is written to this block
   &cbBuff)) != NO_ERROR)     //of memory

    printf("Error: %ld\n\n", res);     //If it fails print the error
else
printf("Universal Name: \t%s\n\n",  //Otherwise print the results
puni->lpUniversalName);  //using the pointer to the REMOTE_NAME_INFO_LEVEL structure

 //Now call WNetGetUniversalName using the REMOTE_NAME_INFO_LEVEL option
  printf("Call WNetGetUniversalName using REMOTE_NAME_INFO_LEVEL.\n");
  if((res = WNetGetUniversalName((LPTSTR)argv[1],
     REMOTE_NAME_INFO_LEVEL,
        (LPVOID) &szBuff,    //Again the structure is written to
       &cbBuff)) != NO_ERROR)     //this block of memory

    printf("Error: %ld\n", res);    //If it fails print the error
  else
    printf("Universal Name: \t%s\n"    //Otherwise print the results
         "Connection Name:\t%s\n"    //using the pointer to the REMOTE_NAME_INFO_LEVEL structure
       "Remaining Path: \t%s\n",
          prni->lpUniversalName,
          prni->lpConnectionName,
          prni->lpRemainingPath);
  return;
}


Retrieving the Connection Name

Windows NT Only

To retrieve the name of the network resource associated with a local device, an application can use the WNetGetConnection function, as shown in the following example.

CHAR szDeviceName[80];
DWORD dwResult, cchBuff = sizeof(szDeviceName);

dwResult = WNetGetConnection("z:",
    (LPSTR) szDeviceName,
    &cchBuff);

switch (dwResult)
{
    case NO_ERROR:
        TextOut(hdc, 10, 10, (LPSTR) szDeviceName,
            lstrlen((LPSTR) szDeviceName));
        break;

    case ERROR_NOT_CONNECTED:
        TextOut(hdc, 10, 10, "Device z: not connected.", 24);

    case ERROR_CONNECTION_UNAVAIL:

        // A connection is remembered but not connected.

        TextOut(hdc, 10, 10, "Connection unavailable.", 23);

    default:

        // An application-defined error handler is demonstrated in the
        // section titled "Retrieving Network Errors."

        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetConnection");
        return FALSE;
}


Retrieving the User Name

Windows NT Only

To retrieve the name of the user associated either with a local device connected to a network resource or with the name of a network, an application can call the WNetGetUser function. The following example uses the device name to retrieve the name of the user.

CHAR szUserName[80];
DWORD dwResult, cchBuff = 80;

dwResult = WNetGetUser("z:",
    (LPSTR) szUserName,
    &cchBuff);

if(dwResult == NO_ERROR)
    TextOut(hdc, 10, 10,
        (LPSTR) szUserName,
        lstrlen((LPSTR) szUserName));

else {
    // An application-defined error handler is demonstrated in the
    // section titled "Retrieving Network Errors."

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetUser");
    return FALSE;
}


Canceling a Network Connection

Windows NT Only

To cancel a connection to a network resource, an application can call the WNetCancelConnection2 function, as shown in the following example.

DWORD dwResult;

dwResult = WNetCancelConnection2("z:",
    CONNECT_UPDATE_PROFILE, // remove connection from profile
    FALSE);                 //fail if open files or jobs

if (dwResult == ERROR_NOT_CONNECTED)
{
    TextOut(hdc, 10, 10, "Drive z: not connected.", 23);
    return FALSE;
}

else if(dwResult != NO_ERROR)
{
    // An application-defined error handler is demonstrated in the
    // section titled "Retrieving Network Errors."

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCancelConnection2");
    return FALSE;
}

TextOut(hdc, 10, 10, "Connection closed for z:.", 25);

The WNetCancelConnection function is supported for compatibility with earlier versions of Windows for Workgroups. For new applications, use WNetCancelConnection2.


Retrieving Network Errors

Windows NT Only

When one of the WNet functions returns WN_EXTENDED_ERROR, an application can call the WNetGetLastError function to get more information about the error that occurred. This information is usually specific to the network provider.

The following example illustrates an application-defined error-handling function (NetErrorHandler) that takes three arguments: a window handle, the error code returned by one of the WNet functions, and the name of the function that produced the error. If the error code is WN_EXTENDED_ERROR, NetErrorHandler calls WNetGetLastError to get extended error information.

BOOL WINAPI NetErrorHandler(HWND hwnd,
                            DWORD dwErrorCode,
                            LPSTR lpszFunction)
{
    DWORD dwWNetResult, dwLastError;
    CHAR szError[256];
    CHAR szCaption[256];
    CHAR szDescription[256];
    CHAR szProvider[256];

    // The following code performs standard error-handling.

    if (dwErrorCode != ERROR_EXTENDED_ERROR)
    {
        wsprintf((LPSTR) szError, "%s failed; \nResult is %ld",
            lpszFunction, dwErrorCode);
        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);
        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);
        return TRUE;
    }

    // The following code performs error-handling when the
    // ERROR_EXTENDED_ERROR return value indicates that WNetGetLastError
    // can retrieve additional information.

    else
    {
        dwWNetResult = WNetGetLastError(&dwLastError,
            (LPSTR) szDescription,  // buffer for error description
            sizeof(szDescription),
            (LPSTR) szProvider,     // buffer for provider name
            sizeof(szProvider));

        if(dwWNetResult != NO_ERROR) {
            wsprintf((LPSTR) szError,
                "WNetGetLastError failed; error %ld", dwWNetResult);
            MessageBox(hwnd, (LPSTR) szError,
                "WNetGetLastError", MB_OK);
            return FALSE;
        }

        wsprintf((LPSTR) szError,
            "%s failed with code %ld;\n%s",
            (LPSTR) szProvider, dwLastError, (LPSTR) szDescription);
        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);
        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);
        return TRUE;
    }
}


Windows Networking Reference

The following elements are used with Windows networking.

  • Windows Networking Functions
  • Windows Networking Structures


Windows Networking Functions

The following functions are used in Windows networking.

WNetAddConnection
WNetAddConnection2
WNetAddConnection3
WNetCancelConnection
WNetCancelConnection2
WNetCloseEnum
WNetConnectionDialog
WNetConnectionDialog1
WNetDisconnectDialog
WNetDisconnectDialog1
WNetEnumResource
WNetGetConnection
WNetGetLastError
WNetGetNetworkInformation
WNetGetProviderName
WNetGetResourceInformation
WNetGetResourceParent
WNetGetUniversalName
WNetGetUser
WNetOpenEnum
WNetUseConnection


WNetAddConnection

The WNetAddConnection function enables the calling application to connect a local device to a network resource. A successful connection is persistent, meaning that Windows automatically restores the connection during subsequent logon operations.

This function is provided for compatibility with earlier versions of Microsoft Windows. For new applications, use the WNetAddConnection2 function.

DWORD WNetAddConnection(
  LPTSTR lpRemoteName, // pointer to network device name
  LPTSTR lpPassword,   // pointer to password
  LPTSTR lpLocalName   // pointer to local device name
);

Parameters

lpRemoteName
Points to a null-terminated string that specifies the network resource to connect to.
lpPassword
Points to a null-terminated string that specifies the password to be used to make a connection. This parameter is usually the password associated with the current user.

If this parameter is NULL, the default password is used. If the string is empty, no password is used.

lpLocalName
Points to a null-terminated string that specifies the name of a local device to be redirected, such as F: or LPT1. The case of the characters in the string is not important. If the string is NULL, a connection to the network resource is made without redirecting the local device.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_ACCESS_DENIED | Access is denied.
ERROR_ALREADY_ASSIGNED | The device specified in the lpLocalName parameter is already connected.
ERROR_BAD_DEV_TYPE | The device type and the resource type do not match.
ERROR_BAD_DEVICE | The value specified in lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified in the lpRemoteName parameter is not valid or cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified in lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH | The operation cannot be performed because either a network component is not started or the specified name cannot be used.
ERROR_NO_NETWORK | The network is not present.

The function returns error codes and sets the error code values returned by GetLastError.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetCancelConnection, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetAddConnection2

The WNetAddConnection2 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection2 function supersedes the WNetAddConnection function. If you pass a handle to a window that the provider of network resources can use as an owner window for dialog boxes, use the WNetAddConnection3 function.

DWORD WNetAddConnection2(
  LPNETRESOURCE lpNetResource,  // points to structure that
                                // specifies connection details
  LPCTSTR lpPassword,           // points to password string
  LPCTSTR lpUsername,           // points to user name string
  DWORD dwFlags                 // set of bit flags that specify
                                // connection options
);

Parameters

lpNetResource
Points to a NETRESOURCE structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:
Member | Description
dwType | Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
lpLocalName | Points to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName | Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length. The string must follow the network provider's naming conventions.
lpProvider | Points to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL or points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by lpRemoteName.
You should set this member only if you know for sure which network provider you want to use. Otherwise, let the operating system determine which provider the network name maps to.
If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

The WNetAddConnection2 function ignores the other members of the NETRESOURCE structure.

lpPassword
Points to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

lpUsername
Points to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. The user context for the process provides the default user name.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

dwFlags
A set of bit flags that specify connection options. The following bit flag constant is currently defined:
Value Meaning
CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on.

The operating system remembers only successful connections that redirect local devices. It does not remember unsuccessful connections or deviceless connections. A deviceless connection occurs when lpLocalName is NULL or points to an empty string.

If this bit flag is clear, the operating system will not automatically restore the connection at logon.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. Returning an error code provides compatibility with the behavior of the Windows 3.1 function WNetAddConnection. You can also call the GetLastError function to obtain the (same) error code. One of the following error codes may be returned when WNetAddConnection2 fails:

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEV_TYPE | The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_BAD_PROVIDER | The value specified by lpProvider does not match any provider.
ERROR_BUSY | The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED | The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers, or by a called resource.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified in lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occured. Call the WNetGetLastError function to get a description of the error.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH | A network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK | There is no network present.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection, WNetAddConnection3, WNetCancelConnection2, WNetGetConnection, WNetGetLastError, NETRESOURCE


WNetAddConnection3

The WNetAddConnection3 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection3 function is similar to the WNetAddConnection2 function. The main difference is that WNetAddConnection3 has an additional parameter, a handle to a window that the provider of network resources can use as an owner window for dialog boxes.

DWORD WNetAddConnection3(
  HWND hwndOwner,               // handle to an owner window for
                                // network provider dialog boxes
  LPNETRESOURCE lpNetResource,  // pointer to structure that
                                // specifies connection details
  LPTSTR lpPassword,            // pointer to password string
  LPTSTR lpUserName,            // pointer to user name string
  DWORD dwFlags                 // set of bit flags that specify
                                // connection options
);

Parameters

hwndOwner
Specifies a window that the provider of network resources can use as an owner window for dialog boxes.

The hwndOwner parameter may be NULL. If it is, a call to WNetAddConnection3 is equivalent to calling the WNetAddConnection2 function.

lpNetResource
Points to a NETRESOURCE data structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:
Member | Description
dwType | Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
lpLocalName | Points to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName | Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length . The string must follow the network provider's naming conventions.
lpProvider | Points to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL or points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by lpRemoteName.
You should set this member only if you know for sure which network provider you want to use. Otherwise, let the operating system determine which network provider the network name maps to.
If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

The WNetAddConnection3 function ignores the other members of the NETRESOURCE structure.

lpPassword
Points to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

lpUserName
Points to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. The user context for the process provides the default user name.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

dwFlags
A set of bit flags that specify connection options. The following bit flag constants are currently defined:
Value Meaning
CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on.

The operating system remembers only successful connections that redirect local devices. It does not remember unsuccessful connections and deviceless connections. A deviceless connection occurs when lpLocalName is NULL or points to an empty string.

If this bit flag is clear, the operating system will not automatically restore the connection at logon.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. Returning an error code provides compatibility with the behavior of the Windows 3.1 function WNetAddConnection. You can also call the GetLastError function to obtain the (same) error code. One of the following error codes may be returned when WNetAddConnection3 fails:

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEV_TYPE | The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_BAD_PROVIDER | The value specified by lpProvider does not match any provider.
ERROR_BUSY | The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED | The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers or by a called resource.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified in lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occured. Call the WNetGetLastError function to get a description of the error.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH | A network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK | There is no network present.

Remarks

Windows CE: Windows CE does not support "drive-letters" (for example, "F:") as local names of redirected resources. The lpLocalName field of the NETRESOURCE structure can contain any string of up to 64 characters long. If the local name is NULL or empty, the resource is connected without a local name. If it is "*", the default name will be constructed as "<share> on <server>" extracted from the remote name of "\\server\share".

Except for nameless connections, the connected resource will appear as a subfolder under the \NETWORK directory. The subfolder is named after the lpLocalName string.

Windows CE supports only the "Microsoft Windows Network" provider. Persistent connections are stored in the registry and not automatically restored when the user logs in.

QuickInfo

Windows NT: Use version 3.5 or later.
Windows: Unsupported.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetCancelConnection

The WNetCancelConnection function breaks an existing network connection.

The function is provided for compatibility with earlier versions of Microsoft Windows. For new applications, use the WNetCancelConnection2 function.

DWORD WNetCancelConnection(
  LPTSTR lpName,  // pointer to resource name to be disconnected
  BOOL fForce     // flag for unconditional disconnect
);

Parameters

lpName
Points to a null-terminated string that specifies the name of either the redirected local device or the remote network resource to disconnect from. When this parameter specifies a redirected local device, only the specified device redirection is broken. If the parameter specifies a remote network resource, only the connections to remote networks without devices are broken.
fForce
Specifies whether the disconnection is to occur even if there are open files or jobs on the connection. If this parameter is FALSE, the function fails if there are open files or jobs.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NOT_CONNECTED | The name specified by the lpName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES | There are open files, and the fForce parameter is FALSE.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetCancelConnection2

The WNetCancelConnection2 function breaks an existing network connection. It can also be used to remove remembered network connections that are not currently connected. This function supersedes WNetCancelConnection.

DWORD WNetCancelConnection2(
  LPTSTR lpName,  // pointer to resource name to disconnect
  DWORD dwFlags,  // connection type flags
  BOOL fForce     // flag for unconditional disconnect
);

Parameters

lpName
Points to a null-terminated string that specifies the name of either the redirected local device or the remote network resource to disconnect from. If this parameter specifies a redirected local resource, only the specified redirection is broken; otherwise, all connections to the remote network resource are broken.
dwFlags
Specifies a bitmask for the connection type. The following values are defined:
Value | Meaning
0 | No stored information about the connection is updated. If the connection was marked as persistent in the registry, Windows will still restore the connection at the next logon. If the connection was not marked as persistent, the function ignores the setting of the CONNECT_UPDATE_PROFILE flag.
CONNECT_UPDATE_PROFILE | The user profile is updated with the information that this is no longer a persistent connection. Windows will not restore this connection during subsequent logon operations. Disconnecting resources using remote names has no effect on persistent connections.

fForce
Specifies whether the disconnection should occur even if there are open files or jobs on the connection. If this parameter is FALSE, the function fails if there are open files or jobs.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NOT_CONNECTED | The name specified by the lpName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES | There are open files, and the fForce parameter is FALSE.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection, WNetAddConnection2, WNetAddConnection3, WNetCancelConnection, WNetGetConnection, WNetGetLastError


WNetCloseEnum

The WNetCloseEnum function ends a network resource enumeration started by the WNetOpenEnum function.

DWORD WNetCloseEnum(
  HANDLE hEnum   // handle to enumeration
);

Parameters

hEnum
Identifies an enumeration instance. This handle must be returned by the WNetOpenEnum function.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_NO_NETWORK | A network is not present. This condition is tested before the handle specified in the hEnum parameter is tested for validity.
ERROR_INVALID_HANDLE | hEnum is not a valid handle.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with Windows NT, the function also sets the error code value returned by GetLastError.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetEnumResource, WNetGetLastError, WNetOpenEnum


WNetConnectionDialog

The WNetConnectionDialog function starts a general browsing dialog box for connecting to network resources.

DWORD WNetConnectionDialog(
  HWND hwnd,     // handle to window owning dialog box
  DWORD dwType   // resource type to allow connections to
);

Parameters

hwnd
Identifies the owning window.
dwType
Specifies the resource type to allow connections to. This parameter can be the following value:
Value | Meaning
RESOURCETYPE_DISK | Connects to disk resources.

Return Values

If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog box, it is 0xFFFFFFFF.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NETWORK | No network is present.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by the GetLastError function.

Remarks

If the user chooses OK in the dialog box, the requested network connections will have been performed when WNetConnectionDialog returns.

If the function attempts to make a connection and the provider returns the message ERROR_INVALID_PASSWORD, Windows prompts the user to enter a password and uses the new password in another attempt to make the connection.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetCancelConnection2, WNetDisconnectDialog, WNetGetLastError


WNetConnectionDialog1

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to network resources.

DWORD WNetConnectionDialog1(
  LPCONNECTDLGSTRUCT lpConnectDlgStruc  pointer to structure
);

Parameters

lpConnectDlgStruct
Pointer to the CONNECTDLGSTRUCT structure, which establishes the browsing dialog parameters.

Return Values

If the user cancels the dialog box, the function returns 0xFFFFFFFF. If the function is successful, it returns WN_SUCCESS. Also, if the call is sucessful, dwDevNum will contain the number of the connected device.

Typically this dialog will only return an error if the user cannot enter a dialog session. This is because errors that occur after a session are reported to the user directly. Error codes include the following.

Value | Meaning
WN_BAD_VALUE | One of the following: CONNDLG_RO_PATH is set and either CONNDLG_USE_MRU is set or lpConnRes->lpRemoteName does not point to a remote name. Both CONNDLG_PERSIST and CONNDLG_NOT_PERSIST are set.
WN_BAD_DEV_TYPE | lpConnRes->dwType is not set to RESOURCETYPE_DISK.
WN_FUNCTION_BUSY | The network provider is busy (possibly initializing). The caller should retry.
WN_NO_NETWORK | The network is not present.
WN_OUT_OF_MEMORY | Insufficient memory to bring up the dialog.
WN_EXTENDED_ERROR | A network specific error occurred. Call WNetGetLastError to obtain a description of the error.

Remarks

Windows CE: Windows CE ignores the dwDevNum member of the CONNECTDLGSTRUCT structure pointed to by the lpConnectDlgStruc parameter.

In Windows CE the dwFlag parameter can be either CONNDLG_RO_PATH or 0.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, CONNECTDLGSTRUCT, WNetConnectionDialog, WNetDisconnectDialog


WNetDisconnectDialog

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from network resources.

DWORD WNetDisconnectDialog(
  HWND hwnd,     // handle to window owning dialog box
  DWORD dwType   // resource type to disconnect from
);

Parameters

hwnd
Identifies the owning window.
dwType
Specifies the resource type to disconnect from. This parameter may be one of the following values:
Value | Meaning
RESOURCETYPE_DISK | Disconnects from disk resources.
RESOURCETYPE_PRINT | Disconnects from print resources.

Return Values

If the function succeeds, the return value is NO_ERROR. If the user cancels out of the dialog box, it is 0xFFFFFFFF.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NETWORK | No network is present.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

Remarks

If the user chooses OK in the dialog box, the requested network disconnections will have been performed when WNetDisconnectDialog returns.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetCancelConnection2, WNetConnectionDialog, WNetGetLastError


WNetDisconnectDialog1

The WNetDisconnectDialog1 function attempts to disconnect from a network resource. If the underlying network returns WN_OPEN_FILES, the function prompts the user for confirmation. If there is any error, it informs the user.

DWORD WNetDisconnectDialog1(
  LPDISCDLGSTRUCT lpDiscDlgStruc  // pointer to structure
);

Parameters

lpDiscDlgStruct
Pointer to the DISCDLGSTRUCT data structure, which specifies the behavior for the disconnect attempt.

Return Values

WN_SUCCESS if the connection is successfully disconnected. Error codes include the following.

Value | Meaning
WN_CANCEL | After the user was prompted for a decision to disconnect, the user elected not to disconnect.
WN_OPEN_FILES | Unable to disconnect because the user is actively using the connection.
WN_FUNCTION_BUSY | The network provider is busy (possibly initializing). The caller should retry.
WN_NO_NETWORK | The network is not present.
WN_OUT_OF_MEMORY | There is not enough memory to bring up the dialog.
WN_EXTENDED_ERROR | A network specific error occurred. Call WNetGetLastError to obtain a description of the error.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetConnectionDialog, WNetConnectionDialog1, WNetDisconnectDialog


WNetEnumResource

The WNetEnumResource function continues a network-resource enumeration started by the WNetOpenEnum function.

DWORD WNetEnumResource(
  HANDLE hEnum,          // handle to enumeration
  LPDWORD lpcCount,      // pointer to entries to list
  LPVOID lpBuffer,       // pointer to buffer for results
  LPDWORD lpBufferSize   // pointer to buffer size variable
);

Parameters

hEnum
Identifies an enumeration instance. This handle must be returned by WNetOpenEnum.
lpcCount
Points to a variable specifying the number of entries requested. If the number requested is 0xFFFFFFFF, the function returns as many entries as possible.

When the function finishes successfully, the variable pointed to by this parameter contains the number of entries actually read.

lpBuffer
Points to the buffer that receives the enumeration results, which are returned as an array of NETRESOURCE structures. The buffer is valid until the next call using the handle given by the hEnum parameter. The order of NETRESOURCE structures in the array is not predictable.
lpBufferSize
Points to a variable that specifies the size, in bytes, of the lpBuffer parameter. If the buffer is too small to receive even one entry, this parameter receives the required size of the buffer.

Return Values

If the function succeeds, the return value is one of the following values:

Value | Meaning
NO_ERROR | The enumeration succeeded, and the buffer contains the requested data. The calling application can continue to call WNetEnumResource to complete the enumeration.
ERROR_NO_MORE_ITEMS | There are no more entries. The buffer contents are undefined.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_INVALID_HANDLE | The handle given by the hEnum parameter is not valid.
ERROR_NO_NETWORK | No network is present. This condition is tested before hEnum is tested for validity.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

Remarks

The WNetEnumResource function does not enumerate users connected to a share; use the NetConnectionEnum function. Also, to enumerate hidden shares, use the NetShareEnum function.

An application cannot set the lpBuffer parameter to NULL and retrieve the required buffer size from the lpBufferSize parameter. Instead, the application should allocate a buffer of a reasonable size — 16 kilobytes (K) is typical — and use the value of lpBufferSize for error detection.

Windows CE: The WNetEnumResource function is called by the network browser application to create lists of available resources on the network

Connections are not automatically stored when the user logs in under Windows CE.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetCloseEnum, WNetGetLastError, WNetOpenEnum


WNetGetConnection

The WNetGetConnection function retrieves the name of the network resource associated with a local device.

DWORD WNetGetConnection(
  LPCTSTR lpLocalName,  // pointer to local name
  LPTSTR lpRemoteName,  // pointer to buffer for remote name
  LPDWORD lpnLength     // pointer to buffer size, in characters
);

Parameters

lpLocalName
Points to a null-terminated string that specifies the name of the local device to get the network name for.
lpRemoteName
Points to a buffer that receives the null-terminated remote name used to make the connection.
lpnLength
Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpRemoteName parameter. If the function fails because the buffer is not big enough, this parameter returns the required buffer size.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_BAD_DEVICE | The string pointed to by the lpLocalName parameter is invalid.
ERROR_NOT_CONNECTED | The device specified by lpLocalName is not redirected.
ERROR_MORE_DATA | The buffer is too small. The lpnLength parameter points to a variable that contains the required buffer size. More entries are available with subsequent calls.
ERROR_CONNECTION_UNAVAIL | The device is not currently connected, but it is a persistent connection.
ERROR_NO_NETWORK | No network is present.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH | None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.

The WNetGetConnection function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

Remarks

Windows CE: The WNetGetConnection function can be used to obtain information on redirected devices, such as printers.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetAddConnection3, WNetGetLastError, WNetGetUser


WNetGetLastError

The WNetGetLastError function retrieves the most recent extended error code set by a Windows network function.

DWORD WNetGetLastError(
  LPDWORD lpError,     // pointer to error code
  LPTSTR lpErrorBuf,   // pointer to string describing error
  DWORD nErrorBufSize, // size of description buffer, in characters
  LPTSTR lpNameBuf,    // pointer to buffer for provider name
  DWORD nNameBufSize   // size of provider name buffer
);

Parameters

lpError
Points to the variable that receives the error code reported by the network provider. The error code is specific to the network provider.
lpErrorBuf
Points to the buffer that receives the null-terminated string describing the error.
nErrorBufSize
Specifies the size, in characters, of the buffer pointed to by the lpErrorBuf parameter. If the buffer is too small for the error string, the string is truncated but still null-terminated. A buffer of at least 256 characters is recommended.
lpNameBuf
Points to the buffer that receives the null-terminated string identifying the network provider that raised the error.
nNameBufSize
Specifies the size, in characters, of the buffer pointed to by the lpNameBuf parameter. If the buffer is too small for the error string, the string is truncated but still null-terminated.

Return Values

If the function successfully obtains the last error reported by the provider, the return value is NO_ERROR. If the caller supplies an invalid buffer, it is ERROR_INVALID_ADDRESS.

Remarks

WNetGetLastError is used to obtain errors that are specific to a network provider. It should be used when a Windows network function (or the GetLastError function) returns ERROR_EXTENDED_ERROR. Like GetLastError, the function returns extended error information, which is maintained on a per-thread basis. Unlike GetLastError, the WNetGetLastError function can also return a string for reporting errors that are not described by any existing error code.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, GetLastError


WNetGetNetworkInformation

The WNetGetNetworkInformation function returns extended information about a specific network whose name was returned by a previous network enumeration.

DWORD WNetGetNetworkInformation(
  LPTSTR lpProvider,                // pointer to provider name
  LPNETINFOSTRUCT lpNetInfoStruct   // pointer to structure
);

Parameters

lpProvider
Pointer to the name of the provider for which information is required.
lpNetInfoStruct
Pointer to the NETINFOSTRUCT structure, which describes the behavior of the network.

Return Values

If the function succeeds, the return value is WN_SUCCESS. If the function fails, one of the following errors will occur:

Value | Meaning
WN_BAD_PROVIDER | lpProvider does not match any running net provider.
WN_BAD_VALUE | The cbStructure, which is a member of the NETINFOSTRUCT structure is not filled in with a valid structure size.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetProviderName


WNetGetProviderName

The WNetGetProviderName function obtains the provider name for a specific type of network.

DWORD WNetGetProviderName(
  DWORD dwNetType,    // specifies network type
  LPTSTR lpProvider,  // pointer to buffer to receive provider name
  LPDWORD lpBufferSize
                      // size of buffer
);

Parameters

dwNetType
Specifies the network type unique to the network. If two networks claim the same type, the function returns the name of the type loaded first. Only the high word of the network type is used. If a network reports a subtype in the low word, it is ignored.
lpProvider
Pointer to a buffer in which to return the provider name.
lpBufferSize
The size, in characters, of the buffer passed to the function call. If the result is WN_MORE_DATA, lpBufferSize contains the buffer size required (in characters) to hold the provider name.

Windows 95: Size is in bytes, not characters. Also, the buffer must be at least 1 byte long.

Return Values

If the function succeeds, the return value is WN_SUCCESS. If the function fails, one of the following errors will occur:

Value | Meaning
WN_MORE_DATA | The buffer is too small to hold the provider name.
WN_NO_NETWORK | The network is not present.
WN_BAD_POINTER | lpProvider or lpBufferSize is invalid.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetNetworkInformation


WNetGetResourceInformation

[This is preliminary documentation and subject to change.]

When provided with a remote path to a network resource, the WNetGetResourceInformation function identifies the network provider that owns the resource and obtains information about the type of the resource. The function is typically used in conjunction with WNetGetResourceParent to parse and interpret a network path typed in by a user.

DWORD WNetGetResourceInformation (
  LPNETRESOURCE lpNetResource,  // Specifies the network resource
                                // for which information is required
  LPVOID lpBuffer,              // Species a buffer to contain
                                // the information
  LPDWORD lpcbBuffer,           // Specifies the size of the buffer
                                // pointed to by lpBuffer
  LPTSTR *lplpSystem            // Pointer to a string in the
                                // output buffer
  );

Parameters

lpNetResource
Specifies the network resource for which information is required. The lpRemoteName parameter specifies the remote path name of the resource, typically typed in by a user. The lpProvider and dwType fields should be filled in if known, because this operation can be expensive, especially without dwType. Otherwise, they should be set to NULL. All other fields of lpNetResource are ignored.
lpBuffer
Pointer to the buffer to receive the result. On a successful return, the first field in the buffer is a NETRESOURCE structure representing that portion of the input resource path that is accessed through Windows networking functions, rather than system functions specific to the input resource type. For example, if the input remote resource path was \\server\share\dir1\dir2, then the output NETRESOURCE contains information about the resource \\server\share. The \dir1\dir2 portion of the path is accessed through file functions. The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage fields of NETRESOURCE are returned, with all other fields being set to NULL.

The lpRemoteName parameter is returned in the same syntax as that returned from an enumeration by the WNetEnumResource function. This allows the caller to perform a string comparison to determine whether the resource passed to WNetGetResourceInformation is the same as the resource returned by a separate call to WNetEnumResource.

lpcbBuffer
Pointer to a location that, on entry, specifies the size, in bytes, of the buffer pointed to by lpBuffer. If the buffer is too small for the result, the function places the required buffer size at this location and returns the error ERROR_MORE_DATA.
lplpSystem
If the function returns successfully, lplpSystem points to a string in the output buffer that specifies the part of the resource that is accessed through system functions. This applies only to functions specific to the resource type rather than Windows networking functions.

For example, if the input remote resource name was \\server\share\dir1\dir2, the lpRemoteName parameter of the output NETRESOURCE structure points to \\server\share. Also, the lplpSystem parameter points to \dir1\dir2. Both strings are stored in the buffer pointed to by lpBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes

Value | Meaning
ERROR_BAD_NET_NAME | The lpRemoteName parameter is not an existing network resource for any network.
ERROR_BAD_DEV_TYPE | The dwType parameter does not match the type of the resource specified by lpRemoteName.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call WNetGetLastError to obtain a description of the error.
ERROR_MORE_DATA | The buffer pointed to by lpBuffer is too small.
ERROR_NO_NETWORK | The network is not present.

Header: Declared in winnetwk.h.
Import Library: Link with mpr.lib.

QuickInfo

Windows NT: Use version 3.5 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetResourceParent


WNetGetResourceParent

[This is preliminary documentation and subject to change.]

The WNetGetResourceParent function determines the parent of a network resource in the network browse hierarchy. Browsing begins at the location of the specified network resource. Use the WNetOpenEnum function to move down the browse hierarchy. Conversely, use the WNetGetResourceInformation and WNetGetResourceParent functions to move up the tree.

DWORD WNetGetResourceParent(
  LPNETRESOURCE lpNetResource,  // Specifies a network resource
                                // for the parent name
  LPVOID lpBuffer,              // Specifies a pointer containing
                                // the parent source
  LPDWORD lpBufferSize,         // Specifies size of location
                                // pointed to by lpbuffer
  );

Parameters

lpNetResource
Specifies the network resource for which the parent name is required. Use the WNetEnumResource, WNetGetResourceInformation or WNetGetResourceParent functions to return information from the NETRESOURCE structure. You can also construct network resource information using the parameters in the NETRESOURCE structure.

The lpRemoteName parameter specifies the remote name of the network resource whose parent is required. The lpProvider parameter specifies the network provider that owns the resource. This must be supplied; otherwise, the function could produce incorrect results. The dwType field should be filled in if known; otherwise, it should be set to NULL.

Note that the caller typically knows the values for lpProvider and dwType after previous calls to WNetGetResourceInformation or WNetGetResourceParent. All other parameters in the NETRESOURCE structure are ignored.

lpBuffer
Pointer to a buffer to receive the result, which is a single NETRESOURCE structure representing the parent resource.

The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage parameters of NETRESOURCE are returned; all other fields are set to NULL.

The lpRemoteName parameter points to the remote name for the parent resource. This name uses the same syntax as that returned from an enumeration by WNetEnumResource. The caller can perform a string comparison to determine whether the WNetGetResourceParent resource is the same as that returned by WNetEnumResource. If the input resource has no parent on any of the networks, the lpRemoteName parameter is returned as NULL. The lpProvider parameter is always returned when the function call is successful. In the dwUsage parameter, the presence of the RESOURCEUSAGE_CONNECTABLE bit means that the parent resource can be connected to, but only when it is available on the network.

lpBufferSize
Points to a location that specifies the size, in bytes, of the buffer pointed to by lpBuffer. If the buffer is too small for the result, the function places the required buffer size at this location and returns ERROR_MORE_DATA.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user is authenticated to the network, but does not have sufficient permissions (access rights).
ERROR_BAD_NET_NAME | The lpRemoteName parameter is not an existing network resource for any network.
ERROR_BAD_PROVIDER | The lpProvider parameter does not match any installed network provider.
ERROR_MORE_DATA | The buffer pointed to by lpBuffer is too small.
ERROR_NOT_AUTHENTICATED | The caller does not have the necessary permissions to obtain the name of the parent.

Remarks

Unlike WNetGetResourceInformation, if the resource includes a parent in its syntax, WNetGetResourceParent returns the parent, whether or not the resource actually exists. The WNetGetResourceParent function should typically be used only by applications that display network resources to the user in a hierarchical fashion. The Windows Explorer and the File Open dialog box are two well-known examples of such applications. No assumptions should be made about the type of resource that will be returned. An example of an inappropriate use of WNetGetResourceParent is to determine the name of the domain to which a specified server belongs. The function may happen to return the correct domain name for some networks in which domains appear directly above servers in the browse hierarchy, but it will give wrong results for other networks.

QuickInfo

Windows NT: Use version 3.5 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetResourceInformation


WNetGetUniversalName

The WNetGetUniversalName function takes a drive-based path for a network resource and obtains a data structure that contains a more universal form of the name.

DWORD WNetGetUniversalName(
  LPCTSTR lpLocalPath,  // pointer to drive-based path for a network
                        // resource
  DWORD dwInfoLevel,    // specifies form of universal name to be
                        // obtained
  LPVOID lpBuffer,      // pointer to buffer that receives universal
                        // name data structure
  LPDWORD lpBufferSize  // pointer to variable that specifies size
                        // of buffer
);

Parameters

lpLocalPath
Points to a null-terminated string that is a drive-based path for a network resource.

For example, if drive H has been mapped to a network drive share, and the network resource of interest is a file named SAMPLE.DOC in the directory \WIN32\EXAMPLES on that share, the drive-based path is H:\WIN32\EXAMPLES\SAMPLE.DOC.

dwInfoLevel
Specifies the type of data structure that the function will store in the buffer pointed to by lpBuffer. This parameter can be one of the following values:
Value | Meaning
UNIVERSAL_NAME_INFO_LEVEL | The function will store a UNIVERSAL_NAME_INFO data structure in the buffer.
REMOTE_NAME_INFO_LEVEL | The function will store a REMOTE_NAME_INFO data structure in the buffer.

The UNIVERSAL_NAME_INFO data structure points to a Universal Naming Convention (UNC) name string.

lpBuffer
Points to a buffer that receives the type of data structure specified by the dwInfoLevel parameter.
lpBufferSize
Points to a variable that specifies the size in bytes of the buffer pointed to by lpBuffer.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the size in bytes of the data structure stored in the buffer. If the function fails because the buffer is too small, indicated by the ERROR_MORE_DATA error code, it sets the variable pointed to by lpBufferSize to the required buffer size.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_BAD_DEVICE | The string pointed to by lpLocalPath is invalid.
ERROR_CONNECTION_UNAVAIL | There is no current connection to the remote device, but there is a remembered (persistent) connection to it.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.
ERROR_MORE_DATA | The buffer pointed to by lpBuffer is too small. The function sets the variable pointed to by lpBufferSize to the required buffer size. More entries are available with subsequent calls.
ERROR_NOT_SUPPORTED | The dwInfoLevel parameter was set to UNIVERSAL_NAME_INFO_LEVEL, but the network provider does not support UNC names. This function is not supported by any of the network providers.
ERROR_NO_NET_OR_BAD_PATH | None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.
ERROR_NO_NETWORK | There is no network present.
ERROR_NOT_CONNECTED | The device specified by lpLocalPath is not redirected.

Remarks

A universal form of a local drive-based path identifies a network resource in an unambiguous, computer-independent manner. The name can then be passed to processes on other computers, allowing those processes to obtain access to the resource.

The WNetGetUniversalName function currently supports one universal name form: universal naming convention (UNC) names, which look like the following:

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the shared network drive is on a server named COOLSERVER, and the share name is HOTSHARE, the UNC name for the network resource whose drive-based name is H:\WIN32\EXAMPLES\SAMPLE.DOC would be

\\coolserver\hotshare\win32\examples\sample.doc

The UNIVERSAL_NAME_INFO data structure contains a pointer to a UNC name string. The REMOTE_NAME_INFO data structure contains a pointer to a UNC name string. It also includes pointers to two other useful strings. A process can pass the REMOTE_NAME_INFO structure's lpszConnectionInfo member into the WNetAddConnection2 function to connect a local device to the network resource, and then append the string pointed to by the lpszRemainingPath member to the local device string. The resulting string can be passed to Win32 functions that use a drive-based path.

Windows CE: Windows CE does not have drive letters. The lpLocalPath should point to the subfolder in the \NETWORK directory.

QuickInfo

Windows NT: Use version 3.5 or later.
Windows: Unsupported.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, REMOTE_NAME_INFO, UNIVERSAL_NAME_INFO, WNetAddConnection2, WNetGetLastError


WNetGetUser

The WNetGetUser function retrieves the current default user name or the user name used to establish a network connection.

DWORD WNetGetUser(
  LPCTSTR lpName,     // pointer to local name to get user name for
  LPTSTR lpUserName,  // pointer to buffer for user name
  LPDWORD lpnLength   // pointer to buffer size variable
);

Parameters

lpName
Points to a null-terminated string that specifies either the name of a local device that has been redirected to a network resource, or the remote name of a network resource to which a connection has been made without redirecting a local device.

If this parameter is NULL, Windows returns the name of the current user for the process.

lpUserName
Points to a buffer that receives the null-terminated user name.
lpnLength
Points to a variable that specifies the size, in characters, of the buffer pointed to by lpUserName. If the call fails because the buffer is not big enough, this variable contains the required buffer size.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_NOT_CONNECTED | The device specified by lpName is not a redirected device or a connected network name.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NO_NETWORK | No network is present.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH | None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetConnection, WNetGetLastError


WNetOpenEnum

The WNetOpenEnum function starts an enumeration of network resources or existing connections.

DWORD WNetOpenEnum(
  DWORD dwScope,     // scope of enumeration
  DWORD dwType,      // resource types to list
  DWORD dwUsage,     // resource usage to list
  LPNETRESOURCE lpNetResource,
                     // pointer to resource structure
  LPHANDLE lphEnum   // pointer to enumeration handle buffer
);

Parameters

dwScope
Specifies the scope of the enumeration. This parameter can be one of the following values:
Value | Meaning
RESOURCE_CONNECTED | All currently connected resources (the dwUsage parameter is ignored).
RESOURCE_CONTEXT | Only resources in the network context of the caller (used for a Network Neighborhood view). The dwUsage parameter is ignored.
RESOURCE_GLOBALNET | All resources on the network.
RESOURCE_REMEMBERED | All remembered (persistent) connections (the dwUsage parameter is ignored).

dwType
Specifies the resource types to enumerate. This parameter can be a combination of the following values:
Value | Meaning
RESOURCETYPE_ANY | All resources (this value cannot be combined with RESOURCETYPE_DISK or RESOURCETYPE_PRINT).
RESOURCETYPE_DISK | All disk resources.
RESOURCETYPE_PRINT | All print resources.

If a network provider cannot distinguish between print and disk resources, it may enumerate all resources.

dwUsage
Specifies the resource usage to be enumerated. This parameter can be a combination of the following values:
Value | Meaning
0 | All resources
RESOURCEUSAGE_CONNECTABLE | All connectable resources
RESOURCEUSAGE_CONTAINER | All container resources

This parameter is ignored if the dwScope parameter is not RESOURCE_GLOBALNET.

lpNetResource
Points to a NETRESOURCE structure specifying the container to enumerate.

If this parameter is NULL, the root of the network is assumed. Windows organizes a network as a hierarchy; the root is the topmost container in the network.

If this parameter is not NULL, it must point to a NETRESOURCE structure. This structure can be filled in by the application or be returned by a call to the WNetEnumResource function. The NETRESOURCE structure must specify a container resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the dwUsage member.

To enumerate all network resources, an application can begin the enumeration by calling WNetOpenEnum with lpNetResource set to NULL and then use the returned handle with WNetEnumResource to enumerate resources. If one of the resources in the NETRESOURCE array returned by the WNetEnumResource function is a container resource, WNetOpenEnum can be used to open the resource for further enumeration.

If the dwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.

lphEnum
Points to a variable filled with an enumeration handle that can be used in a subsequent call to WNetEnumResource.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value | Meaning
ERROR_NOT_CONTAINER | The lpNetResource parameter does not point to a container.
ERROR_INVALID_PARAMETER | Either the dwScope or dwType parameter is invalid, or there is a bad combination of parameters.
ERROR_NO_NETWORK | No network is present.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.

The function returns error codes for compatibility with Windows version 3.1. For compatibility with Windows NT, the function also sets the error code value returned by GetLastError.

Remarks

The exact interpretation of RESOURCE_CONTEXT in the dwScope parameter depends on the networks installed on the machine.

The WNetOpenEnum function is used to begin enumeration of the resources in a single container. The following examples show the hierarchical structure of a Microsoft LAN Manager network and a Novell Netware network:

LanMan (container, in this case the provider)
  ACCOUNTING (container, in this case the domain)
    \\ACCTSPAY (container, in this case the server)
      PAYFILES (disk)
      LASERJET (print)

Netware (container, in this case the provider)
  MARKETING (container, in this case the server)
    SYS (disk, first one on any Netware server)
    ANOTHERVOLUME (disk)
    LASERJET (print)

Windows CE: The WNetOpenEnum function is called by the network browser application to create lists of available resources on the network.

Windows CE does not support the predefined value of RESOURCE_CONTEXT because a device cannot belong to a specific network context.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetCloseEnum, WNetEnumResource, WNetGetLastError


WNetUseConnection

The WNetUseConnection function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetUseConnection function is similar to the WNetAddConnection3 function. The main difference is that WNetUseConnection can automatically select an unused local device to be redirected to the network resource.

Windows 95:
For Windows 95, the lpUserName and lpPassword parameters are in reverse order from those in the Windows NT version as follows:

DWORD WNetUseConnection(
  HWND hwndOwner,
  LPNETRESOURCE lpNetResource,
  LPTSTR lpUserName,
  LPTSTR lpPassword,
  DWORD dwFlags,
  LPTSTR lpAccessName,
  LPDWORD lpBufferSize,
  LPDWORD lpResult
);

For Windows NT the parameter order is as follows:

DWORD WNetUseConnection(
  HWND hwndOwner,
  LPNETRESOURCE lpNetResource,
  LPTSTR lpPassword,
  LPTSTR lpUserName,
  DWORD dwFlags,
  LPTSTR lpAccessName,
  LPDWORD lpBufferSize,
  LPDWORD lpResult
);

Parameters

hwndOwner
Specifies a window that the provider of network resources can use as an owner window for dialog boxes. Use this parameter if CONNECT_INTERACTIVE is set.
lpNetResource
Pointer to a NETRESOURCE structure that specifies details of the proposed connection. The structure contains information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:
Member | Description
dwType | Specifies the type of resource to connect to. It is most efficient to use a specific resource type (such as RESOURCETYPE_DISK or RESOURCETYPE_PRINT). However, if lpLocalName is NULL or points to an empty string and CONNECT_REDIRECT is not set, dwType can be RESOURCETYPE_ANY. This method works only if the function does not automatically choose a device to redirect to the network resource.
lpLocalName | Points to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1." The string is treated in a case-insensitive manner. If the string is empty or if lpLocalName is NULL, a connection to the network occurs without redirection. If CONNECT_REDIRECT is set or the network requires a redirected local device, the function chooses a local device to redirect and returns the name of the device in lpAccessName.
lpRemoteName | Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length. The string must follow the network provider's naming conventions.
lpProvider | Points to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL or points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by lpRemoteName.
You should set this member only if you know for certain which network provider you want to use. Otherwise, let the operating system determine which network provider the network name maps to.
If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

The WNetUseConnection function ignores the other members of the NETRESOURCE structure.

lpPassword
Pointer to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

If the connection fails because of an invalid password and CONNECT_INTERACTIVE is set, the function displays a dialog box asking the user to type the password.

lpUserName
Pointer to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. The user context for the process provides the default user name.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

dwFlags
Specifies any combination of the following values:
Value | Meaning
CONNECT_INTERACTIVE | If this flag is set, the operating system may interact with the user for authentication purposes.
CONNECT_PROMPT | This flag instructs the system not to use any default settings for user names or passwords without offering the user the chance to supply an alternative. This flag is ignored unless CONNECT_INTERACTIVE is set.
CONNECT_REDIRECT This flag forces the redirection of a local device when making the connection. If lpLocalName specifies a local device to redirect, this flag has no effect, because the operating system attempts to redirect the specified device anyway. Otherwise, if the operating system automatically chooses a local device, lpAccessName must point to a return buffer and dwType must not be RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically chosen for redirection only if the network requires a local device to be redirected.
CONNECT_UPDATE_PROFILE This flag instructs the operating system to store the network resource connection.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on. The system remembers only successful connections that redirect local devices. It does not remember unsuccessful connections and deviceless connections. A deviceless connection occurs when lpLocalName is NULL or points to an empty string.

If this bit flag is clear, the operating system will not automatically restore the connection at logon.

lpAccessName
Specifies the name of a buffer that receives system requests on the connection.

If lpLocalName specifies a local device, this buffer is optional, and will have the local device name copied into it. If lpLocalName does not specify a device and the network requires a local device redirection, or if CONNECT_REDIRECT is set, this buffer is required and the name of the redirected local device is returned here. Otherwise, the name copied into the buffer is that of a remote resource. If specified, this buffer must be at least as large as the string pointed to by the lpRemoteName parameter.

lpBufferSize
Specifies the size, in characters, of the lpAccessName buffer passed in. If the call fails because the buffer is not large enough, the function uses this location to return the required buffer size.
lpResult
Pointer to a DWORD that returns additional information about the connection. This parameter can be a combination of the following values:
Value | Meaning
CONNECT_LOCALDRIVE | If this flag is set, the connection was made using a local device redirection. If the lpAccessName parameter points to a buffer, the local device name is copied to the buffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BAD_PROVIDER | The value specified by lpProvider does not match any provider.
ERROR_CANCELLED | The attempt to make the connection was canceled by the user through a dialog box from one of the network resource providers or by a called resource.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To get a description of the error, call the WNetGetLastError function.
ERROR_INVALID_ADDRESS | The caller passed in a pointer to a buffer that could not be accessed.
ERROR_INVALID_PARAMETER This error is a result of one of the following conditions:
  1. The lpRemoteName member is NULL; lpAccessName is not NULL, but lpBufferSize is either NULL or points to zero.
  2. The dwType member is neither RESOURCETYPE_DISK nor RESOURCETYPE_PRINT. In addition, CONNECT_REDIRECT is set in dwFlags, lpLocalName is NULL, or the connection is to a network that requires the redirecting of a local device.
ERROR_INVALID_PASSWORD | The specified password is invalid and CONNECT_INTERACTIVE is not set.
ERROR_MORE_DATA | The lpAccessName buffer is too small. If a local device is redirected, the buffer needs to be large enough to contain the local device name. Otherwise, the buffer needs to be large enough to contain either the string pointed to by lpRemoteName or the name of the connectable resource whose alias is pointed to by lpRemoteName. If this status is returned, then no connection has been made.
ERROR_NO_MORE_ITEMS | The operating system cannot automatically choose a local redirection because all the valid local devices are in use.
ERROR_NO_NET_OR_BAD_PATH | A network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK | There is no network present.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winnetwk.h.
Import Library: Use mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection, WNetAddConnection2, WNetAddConnection3, WnetCancelConnection, WNetGetConnection, WNetGetLastError


Windows Networking Structures

The following structures are used in Windows networking.

CONNECTDLGSTRUCT
DISCDLGSTRUCT
NETINFOSTRUCT
NETRESOURCE
REMOTE_NAME_INFO
UNIVERSAL_NAME_INFO


CONNECTDLGSTRUCT

The CONNECTDLGSTRUCT data structure is used in the WNetConnectionDialog1 function to specify the browsing dialog box parameters.

typedef struct {
    DWORD cbStructure;
    HWND hwndOwner;
    LPNETRESOURCE lpConnRes;
    DWORD dwFlags;
    DWORD dwDevNum;
} CONNECTDLGSTRUCT, *LPCONNECTDLGSTRUCT;

Members

cbStructure
Specifies, in bytes, the size of this structure.
hwndOwner
Specifies the handle of the owning window.
lpConnRes
If lpRemoteName is specified, this member will be entered into the path field of the dialog box. All other members must be set to NULL except dwType which specifies the type of resources of interest, and must be one of RESOURCETYPE_DISK.
Windows NT: Windows NT does not support the RESOURCETYPE_PRINT flag for browsing and connecting to print resources.
dwFlags
Specifies variations in the dialog display. To simulate WNetConnectionDialog, set this member to CONNDLG_USE_MRU. Currently, this may be a combination of the following values.
Value | Meaning
SidTypeUser | The account is a user account.
CONNDLG_RO_PATH | Instead of allowing the user to type in a path, have a read-only path already inserted. This flag should be set only if lpRemoteName is not NULL (or an empty string), and CONNDLG_USE_MRU is not set.
CONNDLG_CONN_POINT Internal flag. Do not use.
Windows NT: Windows NT does not support the CONNDLG_CONN_POINT flag.
CONNDLG_USE_MRU | Enter the most recently used paths into the combo box.
CONNDLG_HIDE_BOX | Show the check box allowing the user to restore the connection at logon.
CONNDLG_PERSIST | Set if the connection is to be restored at logon.
CONNDLG_NOT_PERSIST | Set if the connection is not to be restored at logon.

dwDevNum
If the call is successful, this member returns the number of the device connected to. The value is 1 for A:, 2 for B:, 3 for C:, and so on. If the user made a deviceless connection, the value is 0xFFFFFFFF.

Return Values

The function returns WN_SUCCESS if the call is successful and brings up the dialog. Typically this function will return an error only if the dialog box could not be displayed because errors that occur thereafter are reported to the user directly. If the call is successful, dwDevNum contains the number of the device connected to. If the user cancels the dialog box, the function returns 0xFFFFFFFF.

Error codes include one of the following.

Value Meaning
WN_BAD_VALUE One of two meanings:
  1. CONNDLG_RO_PATH is set and either CONNDLG_USE_MRU is set or lpRemoteName does not point to a remote name.
  2. Both CONNDLG_PERSIST and CONNDLG_NOT_PERSIST are set.

Remarks

If neither CONNDLG_RO_PATH nor CONNDLG_USE_MRU is set in dwFlags, then the request defaults to CONNDLG_RO_PATH if lpRemoteName does not specify a remote path to CONNDLG_USE_MRU. Otherwise, CONNDLG_PERSIST and CONNDLG_NOT_PERSIST cannot both be set. If neither is set, then the dialog defaults to the last option that was selected on this dialog for the particular type of device being connected.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetConnectionDialog1


DISCDLGSTRUCT

The DISCDLGSTRUCT data structure is used in the WNetDisconnectDialog1 function to describe the required behavior for the disconnect attempt.

typedef struct _DISCDLGSTRUCT{
    DWORD cbStructure;
    HWND hwndOwner;
    LPTSTR lpLocalName;
    LPTSTR lpRemoteName;
    DWORD dwFlags;
} DISCDLGSTRUCT,  *LPDISCDLGSTRUCT;

Members

cbStructure
The size, in bytes, of the DISCDLGSTRUCT structure. This structure is filled in by the caller to indicate the size of the structure passed in.
hwndOwner
This specifies the handle to the owning window.
lpRemoteName
Specifies the network resource to disconnect. This member may be set to NULL if lpLocalName is specified. When this occurs, the connection to the resource redirected from lpLocalName is disconnected.
lpLocalName
The local device name that is redirected to the network resource, such as "F:" or "LPT1".
dwFlags
This member can be any combination of the following values:
Value | Meaning
DISC_UPDATE_PROFILE | If this value is set, the connection is no longer persistent (automatically restored every time the user logs on). This flag is valid only if lpLocalName specifies a local device.
DISC_NO_FORCE | If this value is not set, force will be applied when attempting to disconnect (typically because the user has open files). The user will be informed if there are open files to the connection and asked if he or she still wants to disconnect. If so, the disconnect procedure re-attempts with additional force.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures


NETINFOSTRUCT

The NETINFOSTRUCT structure is used in the WNetGetNetworkInformation function to describe the behavior of the network.

typedef struct _NETINFOSTRUCT{
    DWORD cbStructure;
    DWORD dwProviderVersion;
    DWORD dwStatus;
    DWORD dwCharacteristics;
    DWORD dwHandle;
    WORD wNetType;
    DWORD dwPrinters;
    DWORD dwDrives;
} NETINFOSTRUCT,  *LPNETINFOSTRUCT;

Members

cbStructure
The size, in bytes, of the NETINFOSTRUCT structure. The amount is filled in by the caller to indicate the size of the structure passed in. Upon return, it has the size of the structure filled in.
dwProviderVersion
The version number of the network.
dwStatus
The current status of the network provider software. This member can be one of the following values:
Value | Meaning
WN_SUCCESS | The network is up and running.
WN_NO_NETWORK | The network is not currently running.
WN_FUNCTION_BUSY | The network is not currently able to service requests, but should become available. This usually means that the network is starting up.

dwCharacteristics
Characteristics of the network provider software. This is always set to 0.

Windows 95: This member has one or more of the following bit values:

Value | Meaning
NETINFO_DLL16 | The network provider is running as a 16-bit Windows net driver.
NETINFO_DISKRED | The network provider requires a local disk drive device redirected to access server file systems.
NETINFO_PRINTERRED | The network provider requires a local printer port redirected to access server file systems.

dwHandle
The instance handle for the network provider or 16-bit Windows net driver for the network.
wNetType
A network type unique to the network being run. This value associates resources with a specific network when they are persistent or stored in links.
dwPrinters
A bit mask indicating the valid print numbers for redirecting local printer devices, with the lowest-order bit corresponding to LPT1.
Windows 95: This is always set to 0xFFFFFFFF.
dwDrives
A 32-bit mask indicating the valid local disk devices for redirecting disk drives, with the lowest order bit corresponding to A:.
Windows 95: This is always set to 0xFFFFFFFF.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures


NETRESOURCE

The NETRESOURCE structure is returned during enumeration of resources on the network and during enumeration of currently connected resources.

typedef struct _NETRESOURCE {  // nr
    DWORD  dwScope;
    DWORD  dwType;
    DWORD  dwDisplayType;
    DWORD  dwUsage;
    LPTSTR lpLocalName;
    LPTSTR lpRemoteName;
    LPTSTR lpComment;
    LPTSTR lpProvider;
} NETRESOURCE;

Members

dwScope
Specifies the scope of the enumeration. Currently, this member can be one of the following values:
Value | Meaning
RESOURCE_CONNECTED | Currently connected resources (the dwUsage member is undefined).
RESOURCE_GLOBALNET | Resources on the network.
RESOURCE_REMEMBERED | Remembered (persistent) connections (dwUsage is undefined).

dwType
Specifies a bitmask that gives the resource type. Currently, this member can be one of the following values:
Value | Meaning
RESOURCETYPE_ANY | All resources
RESOURCETYPE_DISK | Disk resources
RESOURCETYPE_PRINT | Print resources

dwDisplayType
Specifies how the network object should be displayed in a network browsing user interface. Currently, this member can be the following values:
Value Meaning
RESOURCEDISPLAYTYPE_DOMAIN
The object should be displayed as a domain.
RESOURCEDISPLAYTYPE_GENERIC
The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_SERVER
The object should be displayed as a server.
RESOURCEDISPLAYTYPE_SHARE
The object should be displayed as a sharepoint.

dwUsage
Specifies a bitmask that gives the resource usage. This member is defined only if dwScope is RESOURCE_GLOBALNET. Currently, this member can be one of the following values:
Value | Meaning
RESOURCEUSAGE_CONNECTABLE | This is a connectable resource; the name pointed to by the lpRemoteName member can be passed to the WNetAddConnection function to make a network connection.
RESOURCEUSAGE_CONTAINER | This is a container resource; the name pointed to by the lpRemoteName member can be passed to the WNetOpenEnum function to enumerate the resources in the container.

lpLocalName
Points to the name of a local device if the dwScope member is RESOURCE_CONNECTED or RESOURCE_REMEMBERED. This member is NULL if the connection does not use a device. Otherwise, it is undefined.
lpRemoteName
Points to a remote network name if the entry is a network resource.

If the entry is a current or persistent connection, lpRemoteName points to the network name associated with the name pointed to by the lpLocalName member.

lpComment
Points to a provider-supplied comment.
lpProvider
Points to the name of the provider owning this resource. This member can be NULL if the provider name is unknown.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetAddConnection, WNetCloseEnum, WNetEnumResource, WNetOpenEnum


REMOTE_NAME_INFO

The REMOTE_NAME_INFO data structure contains path and name information about a network resource. The structure contains a member that points to a Universal Naming Convention (UNC) name string for the resource, and two members that point to additional network connection information strings.

typedef struct _REMOTE_NAME_INFO { /* rni */
    LPTSTR  lpUniversalName;
    LPTSTR  lpConnectionName;
    LPTSTR  lpRemainingPath;
} REMOTE_NAME_INFO;

Members

lpUniversalName
Points to a zero-terminated UNC name string.
lpConnectionName
Points to a zero-terminated string that is the name of a network connection.
lpRemainingPath
Points to a zero-terminated UNC name string.

Remarks

The REMOTE_NAME_INFO data structure contains a pointer to a Universal Naming Convention (UNC) name string. UNC names look like this:

\\servername\sharename\path\file

You can pass the REMOTE_NAME_INFO structure's lpConnectionName member to the WNetAddConnection2 function as the lpRemoteName member of the NETRESOURCE structure pointed to by lpNetResource. This lets you connect a local device to a network resource. You can then append the string pointed to by the lpRemainingPath member to the local device string, and pass the resulting string to Win32 functions that use a drive-based path.

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Unsupported.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetAddConnection2, UNIVERSAL_NAME_INFO


UNIVERSAL_NAME_INFO

The UNIVERSAL_NAME_INFO structure contains a pointer to a Universal Naming Convention (UNC) name string.

typedef struct _UNIVERSAL_NAME_INFO { /* uni */
    LPTSTR  lpUniversalName;
} UNIVERSAL_NAME_INFO;

Members

lpUniversalName
Points to a zero-terminated UNC name string.

Remarks

A universal form of a path identifies a network resource in an unambiguous, computer-independent manner. The path can then be passed to processes on other computers, allowing those processes to obtain access to the network resource.

Universal Naming Convention (UNC) names look like this:

\\servername\sharename\path\file

QuickInfo

Windows NT: Use version 3.1 or later.
Windows: Unsupported.
Windows CE: Use version 2.0 or later.
Header: Declared in winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetGetUniversalName, REMOTE_NAME_INFO


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.